API Reference

The FTK API is built around the scientific Python ecosystem and makes extensive use of ND-arrays. Unless otherwise specified, all routines support both CPU and GPU execution. The backend is selected implicitly based on the array types provided as inputs:

The backend-agnostic type hints (ArrayR, ArrayC, ArrayRC) used throughout the API denote placeholders for (NumPy, CuPy) arrays of specific numeric types: their goal is to guide the reader when reading the docstrings, and not to perform runtime type-checking.

Array Types

fourier_toolkit.typing.ArrayR

A (NumPy, CuPy) array of dtype float[32,64].

fourier_toolkit.typing.ArrayC

A (NumPy, CuPy) array of dtype complex[64,128].

fourier_toolkit.typing.ArrayRC

A (NumPy, CuPy) array of dtype (float[32,64], complex[64,128]).

Computing Fourier Sums

fourier_toolkit.u2u(x_spec, v_spec, w, isign)[source]

Multi-dimensional Uniform-to-Uniform Fourier Transform. (\(\tuu\))

Computes the Fourier sum

\[\bbz_{n} = \sum_{m} w_{m} \ee^{ \pm \cj 2\pi \innerProduct{\bbx_{m}}{\bbv_{n}} },\]

where \((\bbx_{m}, \bbv_{n})\) lie on the regular lattice

\[\begin{split}\bbx_{\bbm} &= \bbx_{0} + \Delta_{\bbx} \odot \bbm, \qquad [\bbm]_{d} \in \discreteRange{0}{M_{d}-1}, \\ \bbv_{\bbn} &= \bbv_{0} + \Delta_{\bbv} \odot \bbn, \qquad [\bbn]_{d} \in \discreteRange{0}{N_{d}-1},\end{split}\]

with \(M = \prod_{d} M_{d}\) and \(N = \prod_{d} N_{d}\).

Parameters:

  • x_spec (UniformSpec) – \(\bbx_{m}\) lattice.

  • v_spec (UniformSpec) – \(\bbv_{n}\) lattice.

  • isign (+1, -1) – Exponent sign.

  • w (ArrayRC) – (…, M1,…,MD) weights \(w_{m} \in \bC\).

Returns:

z – (…, N1,…,ND) weights \(z_{n} \in \bC\).

Return type:

ArrayC

Notes

\(\tuu\) transforms for arbitrary (x_spec,v_spec) can be implemented using the CZT algorithm (using 2 FFTs), but a single FFT can be used in some cases. This implementation chooses the (FFT, CZT) per axis to maximize efficiency.

fourier_toolkit.nu2nu(x, v, w, isign, eps=1e-06, **kwargs)[source]

Multi-dimensional NonUniform-to-NonUniform Fourier Transform. (\(\tnunu\))

Computes the Fourier sum

\[\bbz_{n} = \sum_{m} w_{m} \ee^{ \pm \cj 2\pi \innerProduct{\bbx_{m}}{\bbv_{n}} },\]

where \((\bbx_{m}, \bbv_{n}) \in \bR^{D}\).

Parameters:

  • x (ArrayR) – (M, D) support points \(\bbx_{m} \in \bR^{D}\).

  • v (ArrayR) – (N, D) frequencies \(\bbv_{n} \in \bR^{D}\).

  • w (ArrayRC) – (…, M) weights \(w_{m} \in \bC\).

  • isign (+1, -1) – Exponent sign.

  • eps (float) – Target relative error \(\epsilon \in ]0, 1[\).

  • kwargs (dict) – Extra parameters for finufft.Plan. (For advanced users only.)

Returns:

z – (…, N) weights \(z_{n} \in \bC\).

Return type:

ArrayC

Notes

(x,v,w) must have the same numerical precision:

  • (x,v) float32, (w,) complex64

  • (x,v) float64, (w,) complex128

fourier_toolkit.nu2u(x, v_spec, w, isign, eps=1e-06, **kwargs)[source]

Multi-dimensional NonUniform-to-Uniform Fourier Transform. (\(\tnuu\))

Computes the Fourier sum

\[\bbz_{n} = \sum_{m} w_{m} \ee^{ \pm \cj 2\pi \innerProduct{\bbx_{m}}{\bbv_{n}} },\]

where \(\bbx_{m} \in \bR^{D}\), and \(\bbv_{n}\) lies on the regular lattice

\[\bbv_{\bbn} = \bbv_{0} + \Delta_{\bbv} \odot \bbn, \qquad [\bbn]_{d} \in \discreteRange{0}{N_{d}-1},\]

with \(N = \prod_{d} N_{d}\).

Parameters:

  • x (ArrayR) – (M, D) support points \(\bbx_{m} \in \bR^{D}\).

  • v_spec (UniformSpec) – \(\bbv_{n}\) lattice specifier.

  • w (ArrayRC) – (…, M) weights \(w_{m} \in \bC\).

  • isign (+1, -1) – Exponent sign.

  • eps (float) – Target relative error \(\epsilon \in ]0, 1[\).

  • kwargs (dict) – Extra parameters for nu2nu(). (For advanced users only.)

Returns:

z – (…, N1,…,ND) weights \(z_{n} \in \bC\).

Return type:

ArrayC

Notes

  • (x,w) must have the same numerical precision:

    • (x,) float32, (w,) complex64

    • (x,) float64, (w,) complex128

  • This implementation is a thin shell around an \(\tnunu\) transform. This is because type-1 NUFFTs impose limits on domain(x, v_spec) that are a hindrance in practice. The price of relying on an \(\tnunu\) transform is an extra interpolation step after the FFT, but its runtime is rarely the bottleneck. Note that the interpolation step can be done more efficiently via a low-rate filter bank, if needed.

fourier_toolkit.u2nu(x_spec, v, w, isign, eps=1e-06, **kwargs)[source]

Multi-dimensional Uniform-to-NonUniform Fourier Transform. (\(\tunu\))

Computes the Fourier sum

\[\bbz_{n} = \sum_{m} w_{m} \ee^{ \pm \cj 2\pi \innerProduct{\bbx_{m}}{\bbv_{n}} },\]

where \(\bbv_{n} \in \bR^{D}\), and \(\bbx_{m}\) lies on the regular lattice

\[\bbx_{\bbm} = \bbx_{0} + \Delta_{\bbx} \odot \bbm, \qquad [\bbm]_{d} \in \discreteRange{0}{M_{d}-1},\]

with \(M = \prod_{d} M_{d}\).

Parameters:

  • x_spec (UniformSpec) – \(\bbx_{m}\) lattice specifier.

  • v (ArrayR) – (N, D) support points \(\bbv_{n} \in \bR^{D}\).

  • w (ArrayRC) – (…, M1,…,MD) weights \(w_{m} \in \bC\).

  • eps (float) – Target relative error \(\epsilon \in ]0, 1[\).

  • isign (+1, -1) – Exponent sign.

  • kwargs (dict) – Extra parameters for nu2nu(). (For advanced users only.)

Returns:

z – (…, N) weights \(z_{n} \in \bC\).

Return type:

ArrayC

Notes

  • (v,w) must have the same numerical precision:

    • (v,) float32, (w,) complex64

    • (v,) float64, (w,) complex128

  • This implementation is a thin shell around an \(\tnunu\) transform. This is because type-2 NUFFTs impose limits on domain(x_spec, v) that are a hindrance in practice. The price of relying on an \(\tnunu\) transform is an extra interpolation step before the FFT, but its runtime is rarely the bottleneck. Note that the interpolation step can be done more efficiently via a low-rate filter bank, if needed.

Helpers

class fourier_toolkit.UniformSpec(start=None, step=None, num=None, *, center=None, span=None)[source]

Multi-dimensional uniform mesh specifier.

Defines points \(\bbx_{m} \in \bR^{D}\) where each point lies on the regular lattice

\[\bbx_{\bbm} = \bbx_{0} + \Delta_{\bbx} \odot \bbm, \qquad [\bbm]_{d} \in \discreteRange{0}{M_{d}-1}\]
__init__(start=None, step=None, num=None, *, center=None, span=None)[source]

Initialize mesh spec from (start, step, num) or (center, span, num).

Parameters (option 1)

start: tuple[float]

\(\bbx_{0} \in \bR^{D}\)

step: tuple[float]

\(\Delta_{\bbx} \in \bR^{D}\) (signed)

num: tuple[int]

(M1,…,MD) lattice size

Parameters (option 2)

center: tuple[float]

(D,) geometric center

span: tuple[float]

(D,) axial widths

num: tuple[int]

(M1,…,MD) lattice size

Scalars are broadcast to all dimensions.

meshgrid(sparse=False, like=None)[source]

Equivalent of numpy.meshgrid().

Parameters:

like (ArrayRC) – Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as like supports the __array_function__ protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument.

Returns:

mesh – (D,) axial knot coordinates

Return type:

tuple[ArrayR]

knots(like=None)[source]
Parameters:

like (ArrayRC) – Reference object to allow the creation of arrays which are not NumPy arrays. If an array-like passed in as like supports the __array_function__ protocol, the result will be defined by it. In this case, it ensures the creation of an array object compatible with that passed in via this argument.

Returns:

x – (M1,…,MD, D) mesh coordinates

Return type:

ArrayR