Developer Notes

The following are a collection of notes intended for developers and those writing their own applications based on the PMI Toolbox. The intent is to explain the structure and some of the implementation decisions of the toolbox. This is not meant to be exhaustive; when in doubt, check the source code.

Toolbox API

The PMI toolbox is built around the idea of having many small functions, each of which does one relatively simple task. Each function should accept as broad a range of inputs as possible and should exit with a meaningful error message if it is unable to complete its given task. Unless absolutely necessary, all functions should be able to accept as inputs arbitrary numbers and orderings of wavelengths and (where relevant) modulation frequencies, delay times, and gate widths. By keeping the functions small and focused, we improve code re-use and make the functions easier to debug. This also helps keep the number of function arguments to a minimum.

Out of these small functions, larger and still more general functions are built. For example, genBornMat(), the normal user routine for calculating the forward problem, does little more than look at the imaging geometry and the measurement and decide which low-level forward solver is most appropriate for the arguments passed. User applications (for example, HOMER) are, in turn, built on top of these high-level routines.

Calling Conventions

All the functions in the toolbox (well, almost all the functions) use a standard calling procedure; the order of the first three arguments is "SD, Medium, MeasList." It should always be possible to pass an empty list instead of a measurement list, in which case the full measurement list contained in the SD argument will be used instead. Many functions also support a final optional Debug argument (which is not always documented). This argument, if non-zero, prints extra debugging information to the users screen.

For some functions, not all of the three standard arguments are relevant (for example, plotData() doesn't need a Medium structure to display the data correctly). In these cases it is permissible to leave out the useless structure (hence the arguments to plotData() are SD, MeasList, data, etc.).

Directory Structure

Within the root directory of the PMI toolbox are a number of subdirectories. Functions are placed in different subdirectories based on what the function does (e.g., all the visualization functions can all be found in the Visualize directory). There are also directories for local extensions to the toolbox (Local) and for experimental and development code (Development) that is too unstable to keep in the regular Local directory.

The name and purpose of each top-level directory is:

Directory structure within the Forward directory

Within the Forward directory there are a number of subdirectories. These subdirectories are:

Additional Functions

There are a number of low-level routines in the toolbox that, while not things most users will want to call, may be of use to developers. These routines are:

calcExtBnd

Calculate extrapolated boundary length

repackSDAmp

Repack vector coming out of SD Jacobian into the order used by SD.SrcAmp and SD.DetAmp

getImageCharge

Given source Z and extrapolated boundary, calculate the location of the next image charge

moveSrcSlab

Move sources one scattering length into the medium

rowscale

Rescale the rows of a matrix

DPDWBorn1NB, DPDWBorn1SB, DPDWBorn1ZB

Low-level frequency-domain routines to calculate fluence

Hlm2ptNB, Hlm2ptSB, Hlm2ptZB

More low-level frequency-domain routines to calculate fluence

Hlm3ptBorn1NB, Hlm3ptBorn1SB, Hlm3ptBorn1ZB

Low-level frequency-domain routines to calculate Born forward matrix

repackBornFwdMat

Repack matrix from dense matrix (flat storage as returned by the low-level routines) into a sparse block-packed matrix useful for imaging

HlmFullBornNB, HlmFullBornSB, HlmFullBornZB

Low-level FullBorn forward problem solution

MLtoFB

Calculate parameters needed to pack a FullBorn matrix based on the measurement list.

FD_GF, FD_GradGF

Frequency-domain Green's function and its gradient

TD_2ptNB, TD_2ptSB, TD_2ptZB

Low-level time-domain routines to calculate the fluence (matlab)

TD_3ptBorn1NB, TD_3ptBorn1SB, TD_3ptBorn1ZB

Low-level time-domain routines to calculate the Born forward matrix (matlab)

TD_GF, TD_GradGF

Time-domain Green's function and its gradient

mextd2ptNB, mextd2ptSB, mextd2ptZB

Low-level time-domain routines to calculate the time-domain fluence (compiled)

mextd3ptNB, mextd3ptSB, mextd3ptZB

Low-level time-domain routines to calculate the Born forward matrix (compiled)

mexzbnd

Calculate extrapolated boundary length (compiled)

SphHarm, bes_h1, bes_h1d, bes_j, bes_jd, bes_y

Spherical harmonics and spherical bessel functions, used in the analytical solution of spherical perturbations

genSphere, genBlock

Turn a single Medium.Object structure at a single wavelength into a scattered fluence.

Pert_Grad, calcDelMuA, calcDelMuSp

Calculate scattered fluence at multiple wavelengths given list of Object structures.

plotDimensions

Generate aesthetically distributed subplots.