FMMLIB3D Legacy interfaces

The current version of the FMM codes are backward compatible with the previous version of this library: FMMLIB3D. On this page, we refer to these wrappers as the legacy wrappers.

Note

The field associated with the potential returned in FMMLIB3D is negative of the gradient of the potential.

Laplace

The legacy Fortran Laplace wrappers are contained in src/Laplace/lfmm3dwrap_legacy.f and the legacy MATLAB Laplace wrappers are contained in matlab/lfmm3dpart.m and matlab/l3dpartdirect.m.

Currently we have interfaces for the following four Fortran wrappers and two matlab wrappers:

Note

In the Laplace wrappers for FMMLIB3D, the charge strengths, dipole strengths, potentials, and fields are complex numbers as opposed to real numbers for the rest of the library.

Note

lfmm3dpartself and lfmm3dpart are identical subroutines except for their names.

lfmm3dpart and lfmm3dpartself

  • Evaluation points: Sources

  • Interaction kernel: Charges/Dipoles/Charges+Dipoles

  • Outputs requested: Potential/Fields/Potential+Fields

subroutine lfmm3dpart(ier,iprec,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,pot,iffld,fld)

subroutine lfmm3dpartself(ier,iprec,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,pot,iffld,fld)

This subroutine evaluates the potential/field/potential and field

\[u(x) = \sum_{j=1}^{N} c_{j} \frac{1}{\|x-x_{j}\|} - d_{j}\left(v_{j} \cdot \nabla \left( \frac{1}{\|x-x_{j}\|}\right) \right)\]

at the source locations \(x=x_{j}\). When \(x=x_{m}\), the term corresponding to \(x_{m}\) is dropped from the sum.

Input arguments:

  • iprec: integer
    precision flag
    iprec=-2 => tolerance = 0.5d0
    iprec=-1 => tolerance = 0.5d-1
    iprec=0 => tolerance = 0.5d-2
    iprec=1 => tolerance = 0.5d-3
    iprec=2 => tolerance = 0.5d-6
    iprec=3 => tolerance = 0.5d-9
    iprec=4 => tolerance = 0.5d-12
  • nsource: integer

    Number of sources

  • source: double precision(3,nsource)

    Source locations, \(x_{j}\)

  • ifcharge: integer
    charge computation flag
    ifcharge =1 => include charge contribution, otherwise do not
  • charge: double complex(nsource)

    Charge strengths, \(c_{j}\)

  • ifdipole: integer
    dipole computation flag
    ifdipole =1 => include dipole contribution, otherwise do not
  • dipstr: double complex(nsource)

    Dipole strengths, \(d_{j}\)

  • dipvec: double precision(3,nsource)

    Dipole orientation vectors, \(v_{j}\)

  • ifpot: integer
    potential flag
    ifpot =1 => compute potential, otherwise do not
  • iffld: integer
    Field flag
    iffld =1 => compute field, otherwise do not

Output arguments:

  • ier: integer

    error code, currently unused

  • pot: double complex(nsource)

    Potential at source locations, if requested, \(u(x_{j})\)

  • fld: double complex(3,nsource)

    Field at source locations, if requested, -\(\nabla u(x_{j})\)

Back to Laplace legacy wrappers

Back to top

lfmm3dparttarg and l3dpartdirect

  • Evaluation points: Sources/Targets/Sources+targets

  • Interaction kernel: Charges/Dipoles/Charges+Dipoles

  • Outputs requested: Potential/Fields/Potential+Fields

subroutine lfmm3dparttarg(ier,iprec,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,pot,iffld,fld,ntarg,targ,ifpottarg,pottarg,iffldtarg,fldtarg)

This subroutine evaluates the potential/field/potential and field

\[u(x) = \sum_{j=1}^{N} c_{j} \frac{1}{\|x-x_{j}\|} - d_{j}\left(v_{j} \cdot \nabla \left( \frac{1}{\|x-x_{j}\|}\right) \right)\]

at the source locations \(x=x_{j}\)/target locations \(x=t_{j}\)/ source and target locations. When \(x=x_{m}\), the term corresponding to \(x_{m}\) is dropped from the sum.

Input arguments:

  • iprec: integer
    precision flag
    iprec=-2 => tolerance = 0.5d0
    iprec=-1 => tolerance = 0.5d-1
    iprec=0 => tolerance = 0.5d-2
    iprec=1 => tolerance = 0.5d-3
    iprec=2 => tolerance = 0.5d-6
    iprec=3 => tolerance = 0.5d-9
    iprec=4 => tolerance = 0.5d-12
  • nsource: integer

    Number of sources

  • source: double precision(3,nsource)

    Source locations, \(x_{j}\)

  • ifcharge: integer
    charge computation flag
    ifcharge =1 => include charge contribution, otherwise do not
  • charge: double complex(nsource)

    Charge strengths, \(c_{j}\)

  • ifdipole: integer
    dipole computation flag
    ifdipole =1 => include dipole contribution, otherwise do not
  • dipstr: double complex(nsource)

    Dipole strengths, \(d_{j}\)

  • dipvec: double precision(3,nsource)

    Dipole orientation vectors, \(v_{j}\)

  • ifpot: integer
    potential flag
    ifpot =1 => compute potential, otherwise do not
  • iffld: integer
    Field flag
    iffld =1 => compute field, otherwise do not
  • ntarg: integer

    Number of targets

  • targ: double precision(3,ntarg)

    Source locations, \(x_{j}\)

  • ifpottarg: integer
    target potential flag
    ifpottarg =1 => compute potential, otherwise do not
  • iffldtarg: integer
    target field flag
    iffldtarg =1 => compute field, otherwise do not

Output arguments:

  • ier: integer

    error code, currently unused

  • pot: double complex(nsource)

    Potential at source locations, if requested, \(u(x_{j})\)

  • fld: double complex(3,nsource)

    Field at source locations, if requested, -\(\nabla u(x_{j})\)

  • pottarg: double complex(ntarg)

    Potential at target locations, if requested, \(u(t_{j})\)

  • fld: double complex(3,ntarg)

    Field at source locations, if requested, -\(\nabla u(t_{j})\)

Wrapper for direct evaluation of Laplace N-body interactions.

subroutine l3dpartdirect(nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,pot,iffld,fld,ntarg,targ,ifpottarg,pottarg,iffldtarg,fldtarg)

Example:

  • see examples/lfmm3d_legacy_example.f. The corresponding makefile is examples/lfmm3d_legacy_example.make.

Back to Laplace legacy wrappers

Back to top

MATLAB wrappers

  • matlab/lfmm3dpart.m

  • Evaluation points: Sources/Targets/Sources+targets

  • Interaction kernel: Charges/Dipoles/Charges+Dipoles

  • Outputs requested: Potential/Fields/Potential+Fields

function [U]=lfmm3dpart(iprec,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld,ntarg,targ,ifpottarg,iffldtarg)

This subroutine evaluates the potential/field/potential and field

\[u(x) = \sum_{j=1}^{N} c_{j} \frac{1}{\|x-x_{j}\|} - d_{j}\left(v_{j} \cdot \nabla \left( \frac{1}{\|x-x_{j}\|}\right) \right)\]

at the source locations \(x=x_{j}\)/target locations \(x=t_{j}\)/ source and target locations. When \(x=x_{m}\), the term corresponding to \(x_{m}\) is dropped from the sum.

See lfmm3dparttarg and l3dpartdirect for a detailed description of input and output arguments. The output pot,pottarg,fld,fldtarg are contained in the output structure U.

The function can be called in 4 different ways

function [U]=lfmm3dpart(iprec,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec)
function [U]=lfmm3dpart(iprec,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld)
function [U]=lfmm3dpart(iprec,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld,ntarg,targ)
function [U]=lfmm3dpart(iprec,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld,ntarg,targ,ifpottarg,iffldtarg)

The default argument for ifpot,iffld,ifpottarg,iffldtarg is 1, the defaults for ntarg is 0, and targ is zeros(3,1)

Wrapper for direct evaluation of Laplace N-body interactions.

  • matlab/l3dpartdirect.m

function [U]=l3dpartdirect(nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld,ntarg,targ,ifpottarg,iffldtarg)

The function can be called in 4 different ways

function [U]=l3dpartdirect(nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec)
function [U]=l3dpartdirect(nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld)
function [U]=l3dpartdirect(nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld,ntarg,targ)
function [U]=l3dpartdirect(nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld,ntarg,targ,ifpottarg,iffldtarg)

Example:

  • see matlab/test_lfmm3dpart_direct.m.

Back to Laplace legacy wrappers

Back to top

Helmholtz

The legacy Fortran Helmholtz wrappers are contained in src/Helmholtz/hfmm3dwrap_legacy.f and the legacy MATLAB Helmholtz wrappers are contained in matlab/hfmm3dpart.m and matlab/h3dpartdirect.m.

Currently we have interfaces for the following four Fortran wrappers and two matlab wrappers:

Note

hfmm3dpartself and hfmm3dpart are identical subroutines except for their names.

hfmm3dpart and lfmm3dpartself

  • Evaluation points: Sources

  • Interaction kernel: Charges/Dipoles/Charges+Dipoles

  • Outputs requested: Potential/Fields/Potential+Fields

subroutine hfmm3dpart(ier,iprec,zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,pot,iffld,fld)

subroutine hfmm3dpartself(ier,iprec,zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,pot,iffld,fld)

This subroutine evaluates the potential/field/potential and field

\[u(x) = \sum_{j=1}^{N} c_{j} \frac{e^{ik\|x-x_{j}\|}}{\|x-x_{j}\|} - d_{j}\left(v_{j} \cdot \nabla \left( \frac{e^{ik\|x-x_{j}\|}}{\|x-x_{j}\|}\right) \right)\]

at the source locations \(x=x_{j}\). When \(x=x_{m}\), the term corresponding to \(x_{m}\) is dropped from the sum.

Input arguments:

  • iprec: integer
    precision flag
    iprec=-2 => tolerance = 0.5d0
    iprec=-1 => tolerance = 0.5d-1
    iprec=0 => tolerance = 0.5d-2
    iprec=1 => tolerance = 0.5d-3
    iprec=2 => tolerance = 0.5d-6
    iprec=3 => tolerance = 0.5d-9
    iprec=4 => tolerance = 0.5d-12
  • zk: double complex

    Helmholtz parameter, k

  • nsource: integer

    Number of sources

  • source: double precision(3,nsource)

    Source locations, \(x_{j}\)

  • ifcharge: integer
    charge computation flag
    ifcharge =1 => include charge contribution, otherwise do not
  • charge: double complex(nsource)

    Charge strengths, \(c_{j}\)

  • ifdipole: integer
    dipole computation flag
    ifdipole =1 => include dipole contribution, otherwise do not
  • dipstr: double complex(nsource)

    Dipole strengths, \(d_{j}\)

  • dipvec: double precision(3,nsource)

    Dipole orientation vectors, \(v_{j}\)

  • ifpot: integer
    potential flag
    ifpot =1 => compute potential, otherwise do not
  • iffld: integer
    Field flag
    iffld =1 => compute field, otherwise do not

Output arguments:

  • ier: integer

    error code, currently unused

  • pot: double complex(nsource)

    Potential at source locations, if requested, \(u(x_{j})\)

  • fld: double complex(3,nsource)

    Field at source locations, if requested, -\(\nabla u(x_{j})\)

Back to Helmholtz legacy wrappers

Back to top

hfmm3dparttarg and h3dpartdirect

  • Evaluation points: Sources/Targets/Sources+targets

  • Interaction kernel: Charges/Dipoles/Charges+Dipoles

  • Outputs requested: Potential/Fields/Potential+Fields

subroutine hfmm3dparttarg(ier,iprec,zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,pot,iffld,fld,ntarg,targ,ifpottarg,pottarg,iffldtarg,fldtarg)

This subroutine evaluates the potential/field/potential and field

\[u(x) = \sum_{j=1}^{N} c_{j} \frac{e^{ik\|x-x_{j}\|}}{\|x-x_{j}\|} - d_{j}\left(v_{j} \cdot \nabla \left( \frac{e^{ik\|x-x_{j}\|}}{\|x-x_{j}\|}\right) \right)\]

at the source locations \(x=x_{j}\)/target locations \(x=t_{j}\)/ source and target locations. When \(x=x_{m}\), the term corresponding to \(x_{m}\) is dropped from the sum.

Input arguments:

  • iprec: integer
    precision flag
    iprec=-2 => tolerance = 0.5d0
    iprec=-1 => tolerance = 0.5d-1
    iprec=0 => tolerance = 0.5d-2
    iprec=1 => tolerance = 0.5d-3
    iprec=2 => tolerance = 0.5d-6
    iprec=3 => tolerance = 0.5d-9
    iprec=4 => tolerance = 0.5d-12
  • zk: double complex

    Helmholtz parameter, k

  • nsource: integer

    Number of sources

  • source: double precision(3,nsource)

    Source locations, \(x_{j}\)

  • ifcharge: integer
    charge computation flag
    ifcharge =1 => include charge contribution, otherwise do not
  • charge: double complex(nsource)

    Charge strengths, \(c_{j}\)

  • ifdipole: integer
    dipole computation flag
    ifdipole =1 => include dipole contribution, otherwise do not
  • dipstr: double complex(nsource)

    Dipole strengths, \(d_{j}\)

  • dipvec: double precision(3,nsource)

    Dipole orientation vectors, \(v_{j}\)

  • ifpot: integer
    potential flag
    ifpot =1 => compute potential, otherwise do not
  • iffld: integer
    Field flag
    iffld =1 => compute field, otherwise do not
  • ntarg: integer

    Number of targets

  • targ: double precision(3,ntarg)

    Source locations, \(x_{j}\)

  • ifpottarg: integer
    target potential flag
    ifpottarg =1 => compute potential, otherwise do not
  • iffldtarg: integer
    target field flag
    iffldtarg =1 => compute field, otherwise do not

Output arguments:

  • ier: integer

    error code, currently unused

  • pot: double complex(nsource)

    Potential at source locations, if requested, \(u(x_{j})\)

  • fld: double complex(3,nsource)

    Field at source locations, if requested, -\(\nabla u(x_{j})\)

  • pottarg: double complex(ntarg)

    Potential at target locations, if requested, \(u(t_{j})\)

  • fld: double complex(3,ntarg)

    Field at source locations, if requested, -\(\nabla u(t_{j})\)

Wrapper for direct evaluation of Helmholtz N-body interactions.

subroutine h3dpartdirect(zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,pot,iffld,fld,ntarg,targ,ifpottarg,pottarg,iffldtarg,fldtarg)

Example:

  • see examples/hfmm3d_legacy_example.f. The corresponding makefile is examples/hfmm3d_legacy_example.make.

Back to Helmholtz legacy wrappers

Back to top

MATLAB wrappers

  • matlab/hfmm3dpart.m

  • Evaluation points: Sources/Targets/Sources+targets

  • Interaction kernel: Charges/Dipoles/Charges+Dipoles

  • Outputs requested: Potential/Fields/Potential+Fields

function [U]=hfmm3dpart(iprec,zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld,ntarg,targ,ifpottarg,iffldtarg)

This subroutine evaluates the potential/field/potential and field

\[u(x) = \sum_{j=1}^{N} c_{j} \frac{1}{\|x-x_{j}\|} - d_{j}\left(v_{j} \cdot \nabla \left( \frac{1}{\|x-x_{j}\|}\right) \right)\]

at the source locations \(x=x_{j}\)/target locations \(x=t_{j}\)/ source and target locations. When \(x=x_{m}\), the term corresponding to \(x_{m}\) is dropped from the sum.

See hfmm3dparttarg and h3dpartdirect for a detailed description of input and output arguments. The output pot,pottarg,fld,fldtarg are contained in the output structure U.

The function can be called in 4 different ways

function [U]=hfmm3dpart(iprec,zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec)
function [U]=hfmm3dpart(iprec,zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld)
function [U]=hfmm3dpart(iprec,zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld,ntarg,targ)
function [U]=hfmm3dpart(iprec,zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld,ntarg,targ,ifpottarg,iffldtarg)

The default argument for ifpot,iffld,ifpottarg,iffldtarg is 1, the defaults for ntarg is 0, and targ is zeros(3,1)

Wrapper for direct evaluation of Helmholtz N-body interactions.

  • matlab/h3dpartdirect.m

function [U]=h3dpartdirect(zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld,ntarg,targ,ifpottarg,iffldtarg)

The function can be called in 4 different ways

function [U]=h3dpartdirect(zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec)
function [U]=h3dpartdirect(zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld)
function [U]=h3dpartdirect(zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld,ntarg,targ)
function [U]=h3dpartdirect(zk,nsource,source,ifcharge,charge,ifdipole,dipstr,dipvec,ifpot,iffld,ntarg,targ,ifpottarg,iffldtarg)

Example:

  • see matlab/test_hfmm3dpart_direct.m.

Back to Helmholtz legacy wrappers

Back to top