Calculate electrical response induced by drifting charge

Introduction

This package solves Laplace, initial value and other problems in order to produce the current response on electrodes due to drifting of nearby charge.

About the name: the core Laplace problems are solved in pochoir with the finite-difference method (FDM). The core operation of FDM is sometimes described as a “stencil” convolution. The name pochoir describes a stencil-based art style. No constraint is intended on your personal pronunciation of “pochoir”.

Install

pochoir installs in the “usual Python way”. Use of pip and a Python virtual environment is recommended.

python3 -m venv venv
source venv/bin/activiate

Or maybe you prefer direnv

echo layout python3 > .envrc
direnv allow

To install the base support (no support for GPU, plots, config)

pip install git+https://github.com/brettviren/pochoir.git@HEAD

Or for development

git clone git@github.com:brettviren/pochoir.git
cd pochoir
pip install -e .

A number of “extra” support is included mostly for PyTorch, numba, or cupy to try to accelerate some bottlenecks on GPU or via multiprocessing.

pip install -e .[torch,cupy,numba,vtk,plots,hdf5]

Additional setup and of course hardware may be needed to use the GPU support.

Usage

The pochoir command line user interface provides online help:

pochoir

Usage: pochoir [OPTIONS] COMMAND [ARGS]...

  pochoir command line interface

Options:
  -s, --store PATH     File for primary data storage (input and maybe output)
  -o, --outstore PATH  File for output (primary only input)
  --help               Show this message and exit.

Commands:
  bc-interp         Interpolate 2D solution into 3D boundary condition
  domain            Produce a "domain" and store it to the named dataset.
  drift             Calculate drift paths.
  example           Generate a boundary and initial array example (try...
  export-vtk-image  Export a dataset to a vtk file of same name
  fdm               Apply finite-difference method.
  gen               Generate initial and boundary value arrays from a...
  gencfg            Generate JSON configuration files from master file.
  grad              Calculate the gradient of a scalar field.
  induce            Calculate induced current.
  init              Initialize a problem with a shape file.
  ls                List the store store
  move-paths        Move paths along offset vector.
  plot-drift        Visualize 2D or 3D paths
  plot-image        Visualize a dataset as 2D image
  plot-mag          Plot magnitude of a vector field
  plot-quiver       Visualize a 2D or 3D vector field as a "quiver" plot.
  srdot             Apply Ramo theorem dot product.
  starts            Store "starting" points.
  velo              Calculate a velocity field from a potential field
  version           Print the version

Of particular note, to avoid having to always provide the -s/--store option one may set the store via an environment variable:

export POCHOIR_STORE=/path/to/store

Individual commands provide more details on their use:

pochoir fdm --help

Usage: pochoir fdm [OPTIONS]

  Apply finite-difference method.

  Solve Laplace equation given initial/boundary value arrays to produce a
  scalar potential array.

Options:
  -i, --initial TEXT              Input initial value array
  -b, --boundary TEXT             Input the boundary array
  -e, --edges TEXT                Comma separated list of 'fixed' or
                                  'periodic' giving domain edge conditions

  --precision FLOAT               Finish when no changes larger than precision
  --epoch INTEGER                 Number of iterations before any check
  -n, --nepochs INTEGER           Limit number of epochs (def: one epoch)
  --engine [numpy|numba|torch|cupy|cumba]
                                  The FDM engine to use
  -P, --potential TEXT            Output array holding solution for potential
  -I, --increment TEXT            Output array holding increment (error) on
                                  the solution

  --help                          Show this message and exit.

Documentation

The pochoir command attempts to be simple and accessible. However, the calculation it performs is not trivial and has many steps. A user must understand these steps and what pochoir requires.

The documentation to describe these details is in development. For now see:

• ./overview.org gives a conceptual description of the steps that pochoir calculates.
• ./test/test-sandh2d.org a walk through of a full-chain solving a simplified, purely 2D problem.