FMM3D

https://fmm3d.readthedocs.io/en/latest/
Admin
FMM3D is a library for computing N-body interactions governed by Laplace and Helmholtz equations in...
Tokens:63,355
Snippets:266
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Build and install MWrap

Source: https://fmm3d.readthedocs.io/en/latest/install.html

Build and install MWrap after downloading version 0.33.5 or later. Requires flex and bison to be installed. Run make in the MWrap source directory, then copy the mwrap binary to /usr/local/bin/.

```bash
make
sudo cp mwrap /usr/local/bin/

```

--------------------------------

### Install Xcode Command Line Tools on macOS

Source: https://fmm3d.readthedocs.io/en/latest/install.html

Install Command Line Tools on macOS if Xcode is not installed. Run this in a terminal from /Applications/Utilities/.

```bash
xcode-select --install

```

--------------------------------

### Create virtual environment and install numpy

Source: https://fmm3d.readthedocs.io/en/latest/install.html

One-line command to create a virtual environment, activate it, and install numpy. Note the source text shows this as a single line; it is advisable to install numpy into a virtual environment using pip.

```bash
virtualenv -p /usr/bin/python3 env1 . env1/bin/activate pip install numpy
```

--------------------------------

### Install GCC via Homebrew on macOS

Source: https://fmm3d.readthedocs.io/en/latest/install.html

Install GCC on macOS using Homebrew after installing Homebrew from https://brew.sh.

```bash
brew install gcc

```

--------------------------------

### Install numpy in a Python virtual environment

Source: https://fmm3d.readthedocs.io/en/latest/_sources/install.rst.txt

Creates a virtual environment and installs numpy into it using pip. This is the recommended way to install numpy in a virtual environment.

```bash
virtualenv -p /usr/bin/python3 env1
. env1/bin/activate
pip install numpy
```

--------------------------------

### Set custom install prefix with make install PREFIX

Source: https://fmm3d.readthedocs.io/en/latest/install.html

Use to change the default installation directory when running make install. Replace (INSTALL_DIR) with the desired path.

```bash
make install PREFIX=(INSTALL_DIR)
```

--------------------------------

### Install Python 3 on macOS with Homebrew

Source: https://fmm3d.readthedocs.io/en/latest/install.html

Install Python 3 on macOS using Homebrew. Requires Homebrew to be installed first.

```bash
brew install python3

```

--------------------------------

### Install dependencies on Ubuntu Linux

Source: https://fmm3d.readthedocs.io/en/latest/install.html

Install required build tools on Ubuntu Linux using apt-get. Assumes python3 is the default Python.

```bash
sudo apt-get install make build-essential gfortran

```

--------------------------------

### Install Python and pip on Ubuntu Linux

Source: https://fmm3d.readthedocs.io/en/latest/install.html

Install Python 3 and pip on Ubuntu Linux using apt-get. Run this command in a terminal with sudo privileges.

```bash
sudo apt-get install python3 python3-pip

```

--------------------------------

### Install dependencies on Fedora/CentOS Linux

Source: https://fmm3d.readthedocs.io/en/latest/install.html

Install required build tools on Fedora/CentOS Linux using yum.

```bash
sudo yum install make gcc gcc-c++ gcc-gfortran libgomp

```

--------------------------------

### h3ddir: Direct Helmholtz wrapper

Source: https://fmm3d.readthedocs.io/en/latest/julia.html

Wrapper for direct evaluation of Helmholtz N-body interactions. Only returns potentials and gradients at target locations. The `pgt` flag controls evaluation: 1 for potential, 2 for potential and gradient. The `thresh` parameter defaults to 1e-16.

```julia
vals = h3ddir(zk,sources,targets;charges=nothing,
                dipvecs=nothing,pgt=0,nd=1,
                thresh=1e-16)

```

--------------------------------

### Helmholtz FMM subroutine naming: hfmm3d_t_c_g and hfmm3d_<eval-pts>_<int-ker>_<out>

Source: https://fmm3d.readthedocs.io/en/latest/_sources/fortran-c.rst.txt

The first line shows the subroutine name for evaluating the potential and gradient at targets due to charges. The second line gives the general naming pattern for all Helmholtz FMM wrappers, where <eval-pts> is s, t, or st; <int-ker> is c, d, or cd; and <out> is p or g. Append _vec to any routine name to get the vectorized version.

```fortran
hfmm3d_t_c_g
```

```fortran
hfmm3d_<eval-pts>_<int-ker>_<out>
```

--------------------------------

### Laplace FMM Fortran wrapper naming convention

Source: https://fmm3d.readthedocs.io/en/latest/_sources/fortran-c.rst.txt

The Laplace FMM Fortran wrapper subroutines are named by the pattern lfmm3d_<eval-pts>_<int-ker>_<out>, where <eval-pts> is s, t, or st; <int-ker> is c, d, or cd; and <out> is p, g, or h. For example, lfmm3d_t_c_g evaluates the potential and gradient at targets due to charges. Appending _vec to any subroutine name gives a vectorized version that expects interleaved charge strengths, dipole strengths, potentials, and gradients.

```fortran
lfmm3d_t_c_g
```

```fortran
lfmm3d_<eval-pts>_<int-ker>_<out>
```

```fortran
<subroutine name>_vec
```

--------------------------------

### h3ddir: Helmholtz direct evaluation wrapper

Source: https://fmm3d.readthedocs.io/en/latest/matlab.html

Wrapper for direct evaluation of Helmholtz N-body interactions. Only returns potentials and gradients at target locations.

```matlab
function [U] = h3ddir(zk,srcinfo,targ,pgt)
```

--------------------------------

### Laplace wrappers

Source: https://fmm3d.readthedocs.io/en/latest/julia.html

The julia interface provides high-level subroutines for Laplace N-body interactions, including fast multipole implementation (lfmm3d) and direct evaluation (l3ddir).

```APIDOC
## [FUNCTION] lfmm3d

### Description
Wrapper for fast multipole implementation for Laplace N-body interactions. Computes potentials and gradients at source and/or target locations.

### Method
Function call

### Endpoint
`vals = lfmm3d(eps,sources;charges=nothing,dipvecs=nothing,targets=nothing,pg=0,pgt=0,nd=1)`

### Parameters
#### Arguments
- **eps** (double) - Required - precision requested
- **sources** (double(3,n)) - Required - source locations, x_j
- **charges** (double(n,) or double(nd,n)) - Optional - charge densities, c_j
- **dipvec** (double(3,n) or double(nd,3,n)) - Optional - dipole orientation vectors, v_j
- **nd** (integer) - Optional - number of charge/dipole vectors
- **pg** (integer) - Optional - source eval flag: potential at sources evaluated if pg = 1; potential and gradient at sources evaluated if pg=2
- **targets** (double(3,nt)) - Optional - target locations (t_i)
- **pgt** (integer) - Optional - target eval flag: potential at targets evaluated if pgt = 1; potential and gradient at targets evaluated if pgt=2

### Returns
Returns an object val of type FMMVals with the following variables:
- **vals.pot** - potential at source locations, if requested, u(x_j)
- **vals.grad** - gradient at source locations, if requested, ∇u(x_j)
- **vals.pottarg** - potential at target locations, if requested, u(t_i)
- **vals.gradtarg** - gradient at target locations, if requested, ∇u(t_i)
- **vals.ier** - error flag as returned by FMM3D library. A value of 0 indicates a successful call. Non-zero values may indicate insufficient memory available.

### Example
See `lfmmexample.jl`

## [FUNCTION] l3ddir

### Description
Wrapper for direct evaluation of Laplace N-body interactions. Note that this wrapper only returns potentials and gradients at the target locations.

### Method
Function call

### Endpoint
`vals = l3ddir(sources,targets;charges=nothing,dipvecs=nothing,pgt=0,nd=1,thresh=1e-16)`

### Parameters
#### Arguments
- **sources** (double(3,n)) - Required - source locations
- **targets** (double(3,nt)) - Required - target locations
- **charges** (double(n,) or double(nd,n)) - Optional - charge densities
- **dipvecs** (double(3,n) or double(nd,3,n)) - Optional - dipole orientation vectors
- **pgt** (integer) - Optional - target eval flag: potential at targets evaluated if pgt = 1; potential and gradient at targets evaluated if pgt=2
- **nd** (integer) - Optional - number of charge/dipole vectors
- **thresh** (double) - Optional - threshold for direct evaluation (default 1e-16)

### Returns
Returns an object val of type FMMVals with the following variables:
- **vals.pottarg** - potential at target locations, if requested
- **vals.gradtarg** - gradient at target locations, if requested
- **vals.ier** - error flag as returned by FMM3D library. A value of 0 indicates a successful call. Non-zero values may indicate insufficient memory available.

### Example
See `lfmmexample.jl`
```

--------------------------------

### em3ddir

Source: https://fmm3d.readthedocs.io/en/latest/_sources/matlab.rst.txt

Wrapper for direct evaluation of Maxwell N-body interactions. Note that this wrapper only returns potentials and gradients at the target locations.

```APIDOC
## em3ddir

### Description
Wrapper for direct evaluation of Maxwell N-body interactions. Note that this wrapper only returns potentials and gradients at the target locations.

### Method
MATLAB function

### Endpoint
`[U] = em3ddir(srcinfo,targ,pgt)`

### Parameters
#### Input Arguments
- **srcinfo** (structure) - Required - structure containing sourceinfo
  - **srcinfo.sources** (double(3,n)) - Required - source locations, $x_{j}$
  - **srcinfo.nd** (integer) - Optional - number of charge/dipole vectors (default: nd = 1)
  - **srcinfo.charges** (double(nd,n)) - Optional - charge densities, $c_{j}$ (default: term corresponding to charges dropped)
  - **srcinfo.dipoles** (double(nd,3,n)) - Optional - dipole orientation vectors, $v_{j}$ (default: term corresponding to dipoles dropped)
- **targ** (double(3,nt)) - Required - target locations, $t_{i}$
- **pgt** (integer) - Required - target eval flag: potential at targets evaluated if pgt = 1; potential and gradient at targets evaluated if pgt=2

### Returns
- **U.pottarg** - potential at target locations, if requested, $u(t_{i})$
- **U.gradtarg** - gradient at target locations, if requested, $\nabla u(t_{i})$
```

--------------------------------

### Laplace direct evaluation wrapper: l3ddir

Source: https://fmm3d.readthedocs.io/en/latest/matlab.html

Wrapper for direct evaluation of Laplace N-body interactions. Only returns potentials and gradients at target locations. Requires source information in srcinfo and target locations in targ.

```matlab
function [U] = l3ddir(srcinfo,targ,pgt)

```

--------------------------------

### Create and activate Python virtual environment

Source: https://fmm3d.readthedocs.io/en/latest/install.html

Creates and activates a virtual environment named env1 using Python 3. After activation, pip-installed packages go inside env1; exit with 'deactivate'.

```bash
Open a terminal
virtualenv -p /usr/bin/python3 env1
. env1/bin/activate

```

--------------------------------

### hfmm3dparttarg and h3dpartdirect

Source: https://fmm3d.readthedocs.io/en/latest/_sources/legacy.rst.txt

Main FMM wrapper and direct evaluation wrapper for Helmholtz potential/field evaluation at source and/or target locations.

```APIDOC
## hfmm3dparttarg and h3dpartdirect

### Description
Main FMM wrapper and direct evaluation wrapper for Helmholtz potential/field evaluation at source and/or target locations.

### Method
Fortran subroutine

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

### Parameters
- ier (integer) - Output - Error code (currently unused)
- iprec (integer) - Input - Precision flag: -2 => tol=0.5d0, -1 => tol=0.5d-1, 0 => tol=0.5d-2, 1 => tol=0.5d-3, 2 => tol=0.5d-6, 3 => tol=0.5d-9, 4 => tol=0.5d-12
- zk (double complex) - Input - Helmholtz parameter k
- nsource (integer) - Input - Number of sources
- source (double precision(3,nsource)) - Input - Source locations
- ifcharge (integer) - Input - Charge computation flag (1 to include charge contribution)
- charge (double complex(nsource)) - Input - Charge strengths
- ifdipole (integer) - Input - Dipole computation flag (1 to include dipole contribution)
- dipstr (double complex(nsource)) - Input - Dipole strengths
- dipvec (double precision(3,nsource)) - Input - Dipole orientation vectors
- ifpot (integer) - Input - Potential flag (1 to compute potential)
- pot (double complex(nsource)) - Output - Potential at source locations (if requested)
- iffld (integer) - Input - Field flag (1 to compute field)
- fld (double complex(3,nsource)) - Output - Field at source locations (if requested)
- ntarg (integer) - Input - Number of targets
- targ (double precision(3,ntarg)) - Input - Target locations
- ifpottarg (integer) - Input - Target potential flag (1 to compute potential at targets)
- pottarg (double complex(ntarg)) - Output - Potential at target locations (if requested)
- iffldtarg (integer) - Input - Target field flag (1 to compute field at targets)
- fldtarg (double complex(3,ntarg)) - Output - Field at target locations (if requested)

### Description of Evaluation
Evaluates u(x) = sum_j c_j * exp(ik|x-x_j|)/(4*pi*|x-x_j|) - d_j * (v_j . grad(exp(ik|x-x_j|)/(4*pi*|x-x_j|))) at source locations x=x_j and/or target locations x=t_j. When x=x_m, the term for x_m is dropped.

```

--------------------------------

### h3ddir direct Helmholtz evaluation wrapper

Source: https://fmm3d.readthedocs.io/en/latest/_sources/python.rst.txt

Wrapper for direct evaluation of Helmholtz N-body interactions. Returns only potentials and gradients at target locations.

```python
def h3ddir(*,zk,sources,charges=None,dipvec=None,targets=None,pgt=0,nd=1)
```

--------------------------------

### stfmm3d Stokes fast multipole wrapper

Source: https://fmm3d.readthedocs.io/en/latest/_sources/python.rst.txt

Wrapper for fast multipole implementation for Stokes N-body interactions.

```python
def stfmm3d(*,eps,sources,stoklet=None,strslet=None,strsvec=None,rotlet=None,rotvec=None,doublet=None,doubvec=None,targets=None,ifppreg=0,ifppregtarg=0,nd=1)
```
Tokens:
Raw