Merge pull request #37 from ahbarnett/master

docs improvements/typos (MATLAB all kernels; Fortran just Stokes)

matlab/Contents.m

@@ -0,0 +1,35 @@
+% FMM3D: MATLAB/Octave wrappers to 3D fast multipole methods.
+%        Center for Computational Mathematics, Flatiron Institute.
+%
+% Functions:
+%   lfmm3d   - FMM in 3D for Laplace (electrostatic) kernels.
+%   l3ddir   - Direct (slow) 3D Laplace kernel sums (reference for LFMM3D).
+%   hfmm3d   - FMM in 3D for Helmholtz (acoustic frequency-domain) kernel.
+%   h3ddir   - Direct (slow) 3D Helmholtz kernel sums (reference for HFMM3D).
+%   emfmm3d  - FMM in 3D for Maxwell (frequency-domain electromagnetic) kernels.
+%   em3ddir  - Direct (slow) 3D Maxwell kernel sums (reference for EMFMM3D).
+%   stfmm3d  - FMM in 3D for Stokes (viscous fluid hydrodynamic) kernels.
+%   st3ddir  - Direct (slow) 3D Stokes kernel sums (reference for STFMM3D).
+%
+% For tester driver scripts see:
+%   lfmm3dTest
+%   hfmm3dTest
+%   emfmm3dTest
+%   stfmm3dTest
+%   stfmm3dPerfTest
+%
+% For examples of use see:
+%   lfmm3d_example
+%   lfmm3d_big_example
+%   hfmm3d_example
+%   hfmm3d_big_example
+%   emfmm3d_example
+%   stfmm3d_example
+%
+% Legacy codes/interfaces (from the Gimbutas-Greengard CMCL 2012 library):
+%   lfmm3dpart       - Laplace particle targ FMM in R^3.
+%   l3dpartdirect    - Laplace interactions in R^3, direct (slow) evaluation.
+%   hfmm3dpart       - Helmholtz particle targ FMM in R^3.
+%   h3dpartdirect    - Helmholtz interactions in R^3, direct (slow) evaluation.
+%   lfmm3dLegacyTest - Test Laplace particle FMMs in R^3
+%   hfmm3dLegacyTest - Test Helmholtz particle FMMs in R^3

matlab/em3ddir.m

@@ -1,51 +1,17 @@
 function [U] = em3ddir(zk,srcinfo,targ,ifE,ifcurlE,ifdivE)
+% EM3DDIR    Slow direct Maxwell kernel sums (reference for EMFMM3D).
 %
+% U = em3ddir(zk,srcinfo,targ,ifE,ifcurlE,ifdivE)
 %
-%  This subroutine computes
-%      E = curl S_{k}[h_current] + S_{k}[e_current] + grad S_{k}[e_charge]  -- (1)
-%  using the vector Helmholtz fmm.
-%  The subroutine also computes divE, curlE
-%  with appropriate flags
-%  Remark: the subroutine uses a stabilized representation
-%  for computing the divergence by using integration by parts
-%  wherever possible. If the divergence is not requested, then the
-%  helmholtz fmm is called with 3*nd densities, while if the divergence
-%  is requested, then the helmholtz fmm is calld with 4*nd densities
-% 
-%  Args:
+%  Maxwell direct evaluation in R^3: evaluate all pairwise particle
+%  interactions with targets. This is the slow O(N^2) direct code used
+%  as a reference for testing the fast code emfmm3d.
 %
-%  -  zk: complex
-%        Helmholtz parameter, k
-%  -  srcinfo: structure
-%        structure containing sourceinfo
-%     
-%     *  srcinfo.sources: double(3,n)    
-%           source locations, $x_{j}$
-%     *  srcinfo.nd: integer
-%           number of charge/dipole vectors (optional, 
-%           default - nd = 1)
-%     *  srcinfo.h_current: complex(nd,3,n) 
-%           a vector source (optional,
-%           default - term corresponding to h_current dropped) 
-%     *  srcinfo.e_current: complex(nd,3,n) 
-%           b vector source (optional,
-%           default - term corresponding to e_current dropped) 
-%     *  srcinfo.e_charge: complex(nd,n) 
-%           e_charge source (optional, 
-%           default - term corresponding to e_charge dropped)
-%  -  targ: double(3,nt)
-%        target locations, $t_{i}$
-%  -  ifE: integer
-%        E is returned at the target locations if ifE = 1
-%  -  ifcurlE: integer
-%        curl E is returned at the target locations if ifcurlE = 1
-%  -  ifdivE: integer
-%        div E is returned at the target locations if ifdivE = 1
-%  Returns:
-%  
-%  -  U.E: E field defined in (1) above at target locations if requested
-%  -  U.curlE: curl of E field at target locations if requested
-%  -  U.divE: divergence of E at target locations if requested
+%  Kernel definitions, input and outputs arguments are identical to
+%  emfmm3d (see that function for all definitions), except that the first
+%  argument (eps) is absent.
+%
+%  See also: EMFMM3D
 
   if(nargin<4)
     return;

matlab/emfmm3d.m

@@ -1,16 +1,40 @@
 function [U] = emfmm3d(eps,zk,srcinfo,targ,ifE,ifcurlE,ifdivE)
+% EMFMM3D   FMM in 3D for Maxwell (frequency-domain electromagnetic) kernels.
 %
+%  U = emfmm3d(eps,zk,srcinfo,targ,ifE,ifcurlE,ifdivE)
+%
+%  Frequency-domain Maxwell FMM in R^3: evaluate all pairwise particle
+%  interactions (ignoring self-interactions) and
+%  interactions with targets, using the fast multipole method
+%  with precision eps.
+%
+%  Specifically, this subroutine computes a sum for the electric field
+%
+%      E(x) = sum_m curl G_k(x,y^{(m)}) h_current_m
+%                 + G_k(x,y^{(m)}) e_current_m 
+%                 + grad G_k(x,y^{(m)}) e_charge_m
+%
+%  for each requested evaluation point x, where h_current and e_current
+%  are 3-vector densities and e_charge is a scalar density supplied
+%  at each source point y^{(m)}. G_k is the Helmholtz Green function
+%  without the 1/(4pi) scaling:
+%
+%      G_k(x,y) = e^(ik|x-y|)/|x-y|.
+%
+%  In contrast with other FMM routines in the library, this routine
+%  has only 1 option for the evaluation points: they are specified
+%  as targets. If a target x coincides with a source point y^{(m)}
+%  that term in the sum is omitted. 
+%
+%  The electric field is, naturally, a 3-vector at each point x.
+%  With appropriate input flags, the subroutine also computes divE,
+%  curlE. 
 %
-%  This subroutine computes
-%      E = curl S_{k}[h_current] + S_{k}[e_current] + grad S_{k}[e_charge]  -- (1)
-%  using the vector Helmholtz fmm.
-%  The subroutine also computes divE, curlE
-%  with appropriate flags
 %  Remark: the subroutine uses a stabilized representation
 %  for computing the divergence by using integration by parts
 %  wherever possible. If the divergence is not requested, then the
-%  helmholtz fmm is called with 3*nd densities, while if the divergence
-%  is requested, then the helmholtz fmm is calld with 4*nd densities
+%  Helmholtz FMM is called with 3*nd densities, while if the divergence
+%  is requested, then the Helmholtz FMM is called with 4*nd densities
 % 
 %  Args:
 %
@@ -19,8 +43,7 @@
 %  -  zk: complex
 %        Helmholtz parameter, k
 %  -  srcinfo: structure
-%        structure containing sourceinfo
-%     
+%        structure containing the following info about the sources:
 %     *  srcinfo.sources: double(3,n)    
 %           source locations, $x_{j}$
 %     *  srcinfo.nd: integer
@@ -43,11 +66,14 @@
 %        curl E is returned at the target locations if ifcurlE = 1
 %  -  ifdivE: integer
 %        div E is returned at the target locations if ifdivE = 1
+%
 %  Returns:
 %  
-%  -  U.E: E field defined in (1) above at target locations if requested
+%  -  U.E:     E field defined in above equation at targets if requested
 %  -  U.curlE: curl of E field at target locations if requested
-%  -  U.divE: divergence of E at target locations if requested
+%  -  U.divE:  divergence of E at target locations if requested
+%
+% See also: HFMM3D, EM3DDIR
 
   if(nargin<5)
     return;