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:
Data
Functions for importing, exporting, and processing
experimental data.
Doc
Toolbox documentation files
Forward
Functions for solving the forward problem.
Noise
Functions for adding noise to simulated data
Recon
Functions for inverting the forward matrix and
reconstructing images.
Util
Generic, but useful, utility functions
Visualize
Data and volume visualization functions
Local
Functions developed locally and not general enough to include
in the toolbox.
Development
Unstable or experimental functions, will be moved to Local after
they stabilize.
Directory structure within the Forward directory
Within the Forward directory there are
a number of subdirectories. These subdirectories are:
Born
Functions that solve the forward problem in the Born
approximation(s) and related functions
Born/FrequencyDomain
Frequency-domain imaging functions
Born/TimeDomain
Time-domain imaging functions
Born/Correlation
Correlation imaging functions (not implemented)
Born/Fluorescence
Fluorescence imaging functions (not implemented)
Sphere
Functions that solve analytical sphere perturbations
tMCimg
Functions to interface with the "tMCimg" Monte Carlo modeler
tFDimg
Functions to interface with the "tFDimg" finite difference
modeler
TOAST
Function to interface with the "TOAST"
FEM forward modeling package (not implemented)
*/MEX
Hold compiled (MEX) versions of the routines
in the parent directory.
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.
Type "help funcname" from inside Matlab or see the source code for function
documentation.