# Python interface¶

These python interfaces are by Daniel Foreman-Mackey, Jeremy Magland, and Alex Barnett, with help from David Stein. See the installation notes for how to install these interfaces; the main thing to remember is to compile the library before trying to pip install. Below is the documentation for the nine routines. The 2d1 and 2d2 “many vector” interfaces are now also included.

Notes:

1. The module has been designed not to recompile the C++ library; rather, it links to the existing static library. Therefore this library must have been compiled before building python interfaces.
2. In the below, “float” and “complex” refer to double-precision for the default library. One can compile the library for single-precision, but the python interfaces are untested in this case.
3. NumPy input and output arrays are generally passed directly without copying, which helps efficiency in large low-accuracy problems. In 2D and 3D, copying is avoided when arrays are Fortran-ordered; hence choose this ordering in your python code if you are able (see python_tests/accuracy_speed_tests.py).
4. Fortran-style writing of the output to a preallocated NumPy input array is used. That is, such an array is treated as a pointer into which the output is written. This avoids creation of new arrays. The python call return value is merely a status indicator.
finufftpy.nufft1d1(x, c, isign, eps, ms, f, debug=0, spread_debug=0, spread_sort=2, fftw=0, modeord=0, chkbnds=1, upsampfac=2.0)

1D type-1 (aka adjoint) complex nonuniform fast Fourier transform

         nj-1
f(k1) =  SUM c[j] exp(+/-i k1 x(j))  for -ms/2 <= k1 <= (ms-1)/2
j=0

Parameters: x (float[nj]) – nonuniform source points, valid only in [-3pi,3pi] c (complex[nj]) – source strengths isign (int) – if >=0, uses + sign in exponential, otherwise - sign eps (float) – precision requested (>1e-16) ms (int) – number of Fourier modes requested, may be even or odd; in either case the modes are integers lying in [-ms/2, (ms-1)/2] f (complex[ms]) – output Fourier mode values. Should be initialized as a numpy array of the correct size debug (int, optional) – 0 (silent), 1 (print timing breakdown). spread_debug (int, optional) – 0 (silent), 1, 2… (prints spreader info) spread_sort (int, optional) – 0 (don’t sort NU pts in spreader), 1 (do sort), 2 (heuristic decision to sort) fftw (int, optional) – 0 (use FFTW_ESTIMATE), 1 (use FFTW_MEASURE) modeord (int, optional) – 0 (CMCL increasing mode ordering), 1 (FFT ordering) chkbnds (int, optional) – 0 (don’t check NU points valid), 1 (do) upsampfac (float) – either 2.0 (default), or 1.25 (low RAM & small FFT size)

Note

The output is written into the f array.

Returns: 0 if success, 1 if eps too small, 2 if size of arrays to malloc exceed MAX_NF, 4 at least one NU point out of range (if chkbnds true) int

Example

see python_tests/demo1d1.py

finufftpy.nufft1d2(x, c, isign, eps, f, debug=0, spread_debug=0, spread_sort=2, fftw=0, modeord=0, chkbnds=1, upsampfac=2.0)

1D type-2 (aka forward) complex nonuniform fast Fourier transform

c[j] = SUM   f[k1] exp(+/-i k1 x[j])      for j = 0,...,nj-1
k1

where sum is over -ms/2 <= k1 <= (ms-1)/2.

Parameters: x (float[nj]) – nonuniform target points, valid only in [-3pi,3pi] c (complex[nj]) – output values at targets. Should be initialized as a numpy array of the correct size isign (int) – if >=0, uses + sign in exponential, otherwise - sign eps (float) – precision requested (>1e-16) f (complex[ms]) – Fourier mode coefficients, where ms is even or odd In either case the mode indices are integers in [-ms/2, (ms-1)/2] debug (int, optional) – 0 (silent), 1 (print timing breakdown) spread_debug (int, optional) – 0 (silent), 1, 2… (print spreader info) spread_sort (int, optional) – 0 (don’t sort NU pts in spreader), 1 (sort), 2 (heuristic decision to sort) fftw (int, optional) – 0 (use FFTW_ESTIMATE), 1 (use FFTW_MEASURE) modeord (int, optional) – 0 (CMCL increasing mode ordering), 1 (FFT ordering) chkbnds (int, optional) – 0 (don’t check NU points valid), 1 (do) upsampfac (float) – either 2.0 (default), or 1.25 (low RAM & small FFT size)

Note

The output is written into the c array.

Returns: 0 if success, 1 if eps too small, 2 if size of arrays to malloc exceed MAX_NF, 4 at least one NU point out of range (if chkbnds true) int

Example

see python_tests/accuracy_speed_tests.py

finufftpy.nufft1d3(x, c, isign, eps, s, f, debug=0, spread_debug=0, spread_sort=2, fftw=0, upsampfac=2.0)

1D type-3 (NU-to-NU) complex nonuniform fast Fourier transform

         nj-1
f[k]  =  SUM   c[j] exp(+-i s[k] x[j]),      for k = 0, ..., nk-1
j=0

Parameters: x (float[nj]) – nonuniform source points, in R c (complex[nj]) – source strengths isign (int) – if >=0, uses + sign in exponential, otherwise - sign eps (float) – precision requested (>1e-16) s (float[nk]) – nonuniform target frequency points, in R f (complex[nk]) – output values at target frequencies. Should be initialized as a numpy array of the correct size debug (int, optional) – 0 (silent), 1 (print timing breakdown) spread_debug (int, optional) – 0 (silent), 1, 2… (print spreader info) spread_sort (int, optional) – 0 (don’t sort NU pts in spreader), 1 (sort), 2 (heuristic decision to sort) fftw (int, optional) – 0 (use FFTW_ESTIMATE), 1 (use FFTW_MEASURE) upsampfac (float) – either 2.0 (default), or 1.25 (low RAM & small FFT size)

Note

The output is written into the f array.

Returns: 0 if success, 1 if eps too small, 2 if size of arrays to malloc exceed MAX_NF int

Example

see python_tests/accuracy_speed_tests.py

finufftpy.nufft2d1(x, y, c, isign, eps, ms, mt, f, debug=0, spread_debug=0, spread_sort=2, fftw=0, modeord=0, chkbnds=1, upsampfac=2.0)

2D type-1 (aka adjoint) complex nonuniform fast Fourier transform

            nj-1
f(k1,k2) =  SUM c[j] exp(+/-i (k1 x(j) + k2 y[j])),
j=0
for -ms/2 <= k1 <= (ms-1)/2, -mt/2 <= k2 <= (mt-1)/2

Parameters: x (float[nj]) – nonuniform source x-coords, valid only in [-3pi,3pi] y (float[nj]) – nonuniform source y-coords, valid only in [-3pi,3pi] c (complex[nj]) – source strengths isign (int) – if >=0, uses + sign in exponential, otherwise - sign eps (float) – precision requested (>1e-16) ms (int) – number of Fourier modes in x-direction, may be even or odd; in either case the modes are integers lying in [-ms/2, (ms-1)/2] mt (int) – number of Fourier modes in y-direction, may be even or odd; in either case the modes are integers lying in [-mt/2, (mt-1)/2] f (complex[ms,mt]) – output Fourier mode values. Should be initialized as a Fortran-ordered (ie ms fast, mt slow) numpy array of the correct size debug (int, optional) – 0 (silent), 1 (print timing breakdown) spread_debug (int, optional) – 0 (silent), 1, 2… (prints spreader info) spread_sort (int, optional) – 0 (don’t sort NU pts in spreader), 1 (sort), 2 (heuristic decision to sort) fftw (int, optional) – 0 (use FFTW_ESTIMATE), 1 (use FFTW_MEASURE) modeord (int, optional) – 0 (CMCL increasing mode ordering), 1 (FFT ordering) chkbnds (int, optional) – 0 (don’t check NU points valid), 1 (do) upsampfac (float) – either 2.0 (default), or 1.25 (low RAM & small FFT size)

Note

The output is written into the f array.

Returns: 0 if success, 1 if eps too small, 2 if size of arrays to malloc exceed MAX_NF, 4 at least one NU point out of range (if chkbnds true) int

Example

see python/tests/accuracy_speed_tests.py

finufftpy.nufft2d1many(x, y, c, isign, eps, ms, mt, f, debug=0, spread_debug=0, spread_sort=2, fftw=0, modeord=0, chkbnds=1, upsampfac=2.0)
2D type-1 (aka adjoint) complex nonuniform fast Fourier transform, for
multiple strength vectors with same nonuniform points.
              nj-1
f(k1,k2,d) =  SUM c[j,d] exp(+/-i (k1 x(j) + k2 y[j])),
j=0
for -ms/2 <= k1 <= (ms-1)/2, -mt/2 <= k2 <= (mt-1)/2,
d = 0,...,ndata-1

Parameters: x (float[nj]) – nonuniform source x-coords, valid only in [-3pi,3pi] y (float[nj]) – nonuniform source y-coords, valid only in [-3pi,3pi] c (complex[nj,ndata]) – source strengths isign (int) – if >=0, uses + sign in exponential, otherwise - sign eps (float) – precision requested (>1e-16) ms (int) – number of Fourier modes in x-direction, may be even or odd; in either case the modes are integers lying in [-ms/2, (ms-1)/2] mt (int) – number of Fourier modes in y-direction, may be even or odd; in either case the modes are integers lying in [-mt/2, (mt-1)/2] f (complex[ms,mt,ndata]) – output Fourier mode values. Should be initialized as a Fortran-ordered (ie ms fast, mt slow) numpy array of the correct size debug (int, optional) – 0 (silent), 1 (print timing breakdown) spread_debug (int, optional) – 0 (silent), 1, 2… (prints spreader info) spread_sort (int, optional) – 0 (don’t sort NU pts in spreader), 1 (sort), 2 (heuristic decision to sort) fftw (int, optional) – 0 (use FFTW_ESTIMATE), 1 (use FFTW_MEASURE) modeord (int, optional) – 0 (CMCL increasing mode ordering), 1 (FFT ordering) chkbnds (int, optional) – 0 (don’t check NU points valid), 1 (do) upsampfac (float) – either 2.0 (default), or 1.25 (low RAM & small FFT size)

Note

The outputs are written into the f array.

For small problems this routine will be faster than repeated calls to nufft2d1.

Nthreads copies of the fine grid are allocated, limiting this to smaller problem sizes than the plain 2d1 interface.

Returns: 0 if success, 1 if eps too small, 2 if size of arrays to malloc exceed MAX_NF, 4 at least one NU point out of range (if chkbnds true) int

Example

see python/tests/accuracy_speed_tests.py

finufftpy.nufft2d2(x, y, c, isign, eps, f, debug=0, spread_debug=0, spread_sort=2, fftw=0, modeord=0, chkbnds=1, upsampfac=2.0)

2D type-2 (aka forward) complex nonuniform fast Fourier transform

c[j] =   SUM   f[k1,k2] exp(+/-i (k1 x[j] + k2 y[j])),  for j = 0,...,nj-1
k1,k2

where sum is over -ms/2 <= k1 <= (ms-1)/2, -mt/2 <= k2 <= (mt-1)/2

Parameters: x (float[nj]) – nonuniform target x-coords, valid only in [-3pi,3pi] y (float[nj]) – nonuniform target y-coords, valid only in [-3pi,3pi] c (complex[nj]) – output values at targets. Should be initialized as a numpy array of the correct size isign (int) – if >=0, uses + sign in exponential, otherwise - sign eps (float) – precision requested (>1e-16) f (complex[ms,mt]) – Fourier mode coefficients, where ms and mt are either even or odd; in either case their mode range is integers lying in [-m/2, (m-1)/2], with mode ordering in all dimensions given by modeord. Ordering is Fortran-style, ie ms fastest. debug (int, optional) – 0 (silent), 1 (print timing breakdown) spread_debug (int, optional) – 0 (silent), 1, 2… (print spreader info) spread_sort (int, optional) – 0 (don’t sort NU pts in spreader), 1 (sort), 2 (heuristic decision to sort) fftw (int, optional) – 0 (use FFTW_ESTIMATE), 1 (use FFTW_MEASURE) modeord (int, optional) – 0 (CMCL increasing mode ordering), 1 (FFT ordering) chkbnds (int, optional) – 0 (don’t check NU points valid), 1 (do) upsampfac (float) – either 2.0 (default), or 1.25 (low RAM & small FFT size)

Note

The output is written into the c array.

Returns: 0 if success, 1 if eps too small, 2 if size of arrays to malloc exceed MAX_NF, 4 at least one NU point out of range (if chkbnds true) int

Example

see python_tests/accuracy_speed_tests.py

finufftpy.nufft2d2many(x, y, c, isign, eps, f, debug=0, spread_debug=0, spread_sort=2, fftw=0, modeord=0, chkbnds=1, upsampfac=2.0)
2D type-2 (aka forward) complex nonuniform fast Fourier transform, for
multiple coefficient vectors with same nonuniform points.
c[j,d] =  SUM  f[k1,k2,d] exp(+/-i (k1 x[j] + k2 y[j])),
k1,k2

for j = 0,...,nj-1, and d = 0,...,ndata-1
where sum is over -ms/2 <= k1 <= (ms-1)/2, -mt/2 <= k2 <= (mt-1)/2

Parameters: x (float[nj]) – nonuniform target x-coords, valid only in [-3pi,3pi] y (float[nj]) – nonuniform target y-coords, valid only in [-3pi,3pi] c (complex[nj,ndata]) – output values at targets. Should be initialized as a Fortran-ordered numpy array of the correct size isign (int) – if >=0, uses + sign in exponential, otherwise - sign eps (float) – precision requested (>1e-16) f (complex[ms,mt,ndata]) – Fourier mode coefficients, where ms and mt are either even or odd; in either case their mode range is integers lying in [-m/2, (m-1)/2], with mode ordering in all dimensions given by modeord. Ordering is Fortran-style, ie ms fastest. debug (int, optional) – 0 (silent), 1 (print timing breakdown) spread_debug (int, optional) – 0 (silent), 1, 2… (print spreader info) spread_sort (int, optional) – 0 (don’t sort NU pts in spreader), 1 (sort), 2 (heuristic decision to sort) fftw (int, optional) – 0 (use FFTW_ESTIMATE), 1 (use FFTW_MEASURE) modeord (int, optional) – 0 (CMCL increasing mode ordering), 1 (FFT ordering) chkbnds (int, optional) – 0 (don’t check NU points valid), 1 (do) upsampfac (float) – either 2.0 (default), or 1.25 (low RAM & small FFT size)

Note

The outputs are written into the c array.

For small problems this routine will be faster than repeated calls to nufft2d2.

Nthreads copies of the fine grid are allocated, limiting this to smaller problem sizes than the plain 2d2 interface.

Returns: 0 if success, 1 if eps too small, 2 if size of arrays to malloc exceed MAX_NF, 4 at least one NU point out of range (if chkbnds true) int

Example

see python_tests/accuracy_speed_tests.py

finufftpy.nufft2d3(x, y, c, isign, eps, s, t, f, debug=0, spread_debug=0, spread_sort=2, fftw=0, upsampfac=2.0)

2D type-3 (NU-to-NU) complex nonuniform fast Fourier transform

         nj-1
f[k]  =  SUM   c[j] exp(+-i s[k] x[j] + t[k] y[j]),  for k = 0,...,nk-1
j=0

Parameters: x (float[nj]) – nonuniform source point x-coords, in R y (float[nj]) – nonuniform source point y-coords, in R c (complex[nj]) – source strengths isign (int) – if >=0, uses + sign in exponential, otherwise - sign eps (float) – precision requested (>1e-16) s (float[nk]) – nonuniform target x-frequencies, in R t (float[nk]) – nonuniform target y-frequencies, in R f (complex[nk]) – output values at target frequencies. Should be initialized as a numpy array of the correct size debug (int, optional) – 0 (silent), 1 (print timing breakdown) spread_debug (int, optional) – 0 (silent), 1, 2… (print spreader info) spread_sort (int, optional) – 0 (don’t sort NU pts in spreader), 1 (sort), 2 (heuristic decision to sort) fftw (int, optional) – 0 (use FFTW_ESTIMATE), 1 (use FFTW_MEASURE) upsampfac (float) – either 2.0 (default), or 1.25 (low RAM & small FFT size)

Note

The output is written into the f array.

Returns: 0 if success, 1 if eps too small, 2 if size of arrays to malloc exceed MAX_NF int

Example

see python_tests/accuracy_speed_tests.py

finufftpy.nufft3d1(x, y, z, c, isign, eps, ms, mt, mu, f, debug=0, spread_debug=0, spread_sort=2, fftw=0, modeord=0, chkbnds=1, upsampfac=2.0)

3D type-1 (aka adjoint) complex nonuniform fast Fourier transform

               nj-1
f(k1,k2,k3) =  SUM c[j] exp(+/-i (k1 x(j) + k2 y[j] + k3 z[j])),
j=0
for -ms/2 <= k1 <= (ms-1)/2,
-mt/2 <= k2 <= (mt-1)/2,  -mu/2 <= k3 <= (mu-1)/2

Parameters: x (float[nj]) – nonuniform source x-coords, valid only in [-3pi,3pi] y (float[nj]) – nonuniform source y-coords, valid only in [-3pi,3pi] z (float[nj]) – nonuniform source z-coords, valid only in [-3pi,3pi] c (complex[nj]) – source strengths isign (int) – if >=0, uses + sign in exponential, otherwise - sign eps (float) – precision requested (>1e-16) ms (int) – number of Fourier modes in x-direction, may be even or odd; in either case the modes are integers lying in [-ms/2, (ms-1)/2] mt (int) – number of Fourier modes in y-direction, may be even or odd; in either case the modes are integers lying in [-mt/2, (mt-1)/2] mu (int) – number of Fourier modes in z-direction, may be even or odd; in either case the modes are integers lying in [-mu/2, (mu-1)/2] f (complex[ms,mt,mu]) – output Fourier mode values. Should be initialized as a Fortran-ordered (ie ms fastest) numpy array of the correct size debug (int, optional) – 0 (silent), 1 (print timing breakdown) spread_debug (int, optional) – 0 (silent), 1, 2… (prints spreader info) spread_sort (int, optional) – 0 (don’t sort NU pts in spreader), 1 (sort), 2 (heuristic decision to sort) fftw (int, optional) – 0 (use FFTW_ESTIMATE), 1 (use FFTW_MEASURE) modeord (int, optional) – 0 (CMCL increasing mode ordering), 1 (FFT ordering) chkbnds (int, optional) – 0 (don’t check NU points valid), 1 (do) upsampfac (float) – either 2.0 (default), or 1.25 (low RAM & small FFT size)

Note

The output is written into the f array.

Returns: 0 if success, 1 if eps too small, 2 if size of arrays to malloc exceed MAX_NF, 4 at least one NU point out of range (if chkbnds true) int

Example

see python_tests/accuracy_speed_tests.py

finufftpy.nufft3d2(x, y, z, c, isign, eps, f, debug=0, spread_debug=0, spread_sort=2, fftw=0, modeord=0, chkbnds=1, upsampfac=2.0)

3D type-2 (aka forward) complex nonuniform fast Fourier transform

c[j] =   SUM   f[k1,k2,k3] exp(+/-i (k1 x[j] + k2 y[j] + k3 z[j])).
k1,k2,k3
for j = 0,...,nj-1,  where sum is over
-ms/2 <= k1 <= (ms-1)/2, -mt/2 <= k2 <= (mt-1)/2, -mu/2 <= k3 <= (mu-1)/2

Parameters: x (float[nj]) – nonuniform target x-coords, valid only in [-3pi,3pi] y (float[nj]) – nonuniform target y-coords, valid only in [-3pi,3pi] z (float[nj]) – nonuniform target z-coords, valid only in [-3pi,3pi] c (complex[nj]) – output values at targets. Should be initialized as a numpy array of the correct size isign (int) – if >=0, uses + sign in exponential, otherwise - sign eps (float) – precision requested (>1e-16) f (complex[ms,mt,mu]) – Fourier mode coefficients, where ms, mt and mu are either even or odd; in either case their mode range is integers lying in [-m/2, (m-1)/2], with mode ordering in all dimensions given by modeord. Ordering is Fortran-style, ie ms fastest. debug (int, optional) – 0 (silent), 1 (print timing breakdown) spread_debug (int, optional) – 0 (silent), 1, 2… (print spreader info) spread_sort (int, optional) – 0 (don’t sort NU pts in spreader), 1 (sort), 2 (heuristic decision to sort) fftw (int, optional) – 0 (use FFTW_ESTIMATE), 1 (use FFTW_MEASURE) modeord (int, optional) – 0 (CMCL increasing mode ordering), 1 (FFT ordering) chkbnds (int, optional) – 0 (don’t check NU points valid), 1 (do) upsampfac (float) – either 2.0 (default), or 1.25 (low RAM & small FFT size)

Note

The output is written into the c array.

Returns: 0 if success, 1 if eps too small, 2 if size of arrays to malloc exceed MAX_NF, 4 at least one NU point out of range (if chkbnds true) int

Example

see python_tests/accuracy_speed_tests.py

finufftpy.nufft3d3(x, y, z, c, isign, eps, s, t, u, f, debug=0, spread_debug=0, spread_sort=2, fftw=0, upsampfac=2.0)

3D type-3 (NU-to-NU) complex nonuniform fast Fourier transform

         nj-1
f[k]  =  SUM   c[j] exp(+-i s[k] x[j] + t[k] y[j] + u[k] z[j]),
j=0
for k = 0,...,nk-1

Parameters: x (float[nj]) – nonuniform source point x-coords, in R y (float[nj]) – nonuniform source point y-coords, in R z (float[nj]) – nonuniform source point z-coords, in R c (complex[nj]) – source strengths isign (int) – if >=0, uses + sign in exponential, otherwise - sign eps (float) – precision requested (>1e-16) s (float[nk]) – nonuniform target x-frequencies, in R t (float[nk]) – nonuniform target y-frequencies, in R u (float[nk]) – nonuniform target z-frequencies, in R f (complex[nk]) – output values at target frequencies. Should be initialized as a numpy array of the correct size debug (int, optional) – 0 (silent), 1 (print timing breakdown) spread_debug (int, optional) – 0 (silent), 1, 2… (print spreader info) spread_sort (int, optional) – 0 (don’t sort NU pts in spreader), 1 (sort), 2 (heuristic decision to sort) fftw (int, optional) – 0 (use FFTW_ESTIMATE), 1 (use FFTW_MEASURE) upsampfac (float) – either 2.0 (default), or 1.25 (low RAM & small FFT size)

Note

The output is written into the f array.

Returns: 0 if success, 1 if eps too small, 2 if size of arrays to malloc exceed MAX_NF int

Example

see python_tests/accuracy_speed_tests.py