FFT cutile-python API#

nvmath.tile.fft provides cuFFTDx-backed complex and real FFTs for CUDA Tile Python kernels.

The equivalent C++ interface is documented in cuFFTDx in Tile.

A real tile represents a complex signal with a trailing interleaved (real, imaginary) axis of extent 2. Transforms are unnormalized in both directions. Refer to FFT conventions. Use suggested_tile_config() to select batches_per_block and num_worker_warps, as described in Suggested FFT Configuration.

The optional match parameter controls whether suggestions are mapped to a tuned architecture or require an exact architecture match. See Architecture matching.

Quick start#

import cuda.tile as ct
import cupy as cp
import nvmath.tile.fft as mfft


@ct.kernel(num_worker_warps=4)
def fft_kernel(source: ct.Array, destination: ct.Array):
    signal = ct.load(source, (0, 0), shape=(256, 2))
    ct.store(destination, (0, 0), mfft.fft(signal, axis=0))


def main():
    source = cp.zeros((256, 2), dtype=cp.float32)
    source[:, 0] = 1
    destination = cp.zeros_like(source)
    ct.launch(cp.cuda.get_current_stream(), (1, 1, 1), fft_kernel, (source, destination))
    cp.cuda.runtime.deviceSynchronize()
    assert cp.allclose(destination[0], cp.asarray([256, 0], dtype=cp.float32))
    assert cp.allclose(destination[1:], 0, atol=1e-3)


if __name__ == "__main__":
    main()

API reference#

Discrete Fourier transforms inside a CUDA Tile kernel, backed by cuFFTDx.

A complex signal is a real tile with a trailing axis of two holding the interleaved real and imaginary components. The API supports rank-one to rank-three logical signals. Real transforms currently use the full complex layout.

Both transform directions are unnormalized, matching cuFFT. The mandatory axis argument follows NumPy’s indexing convention. Negative values count from the last transform dimension.

nvmath.tile.fft.fft(x, axis)#

Compute an unnormalized forward discrete Fourier transform.

Parameters:
  • x (cuda.tile.Tile) – Real-valued tile with shape (D0, ..., D{RANK-1}, 2) containing interleaved complex values. The API supports one to three logical dimensions. The element type must be float32 or float64.

  • axis (int) – Logical transform dimension. Negative values count from the last transform dimension.

Returns:

Complex spectrum with the same shape and element type as x.

Return type:

cuda.tile.Tile

nvmath.tile.fft.ifft(x, axis)#

Compute an unnormalized inverse discrete Fourier transform.

ifft(fft(x)) equals N * x, where N is the transform extent.

Parameters:
  • x (cuda.tile.Tile) – Real-valued tile with shape (D0, ..., D{RANK-1}, 2) containing an interleaved complex spectrum. The API supports one to three logical dimensions. The element type must be float32 or float64.

  • axis (int) – Logical transform dimension. Negative values count from the last transform dimension.

Returns:

Complex signal with the same shape and element type as x.

Return type:

cuda.tile.Tile

nvmath.tile.fft.rfft(x, axis, complex_layout)#

Compute an unnormalized forward real-to-complex transform.

Parameters:
  • x (cuda.tile.Tile) – Real signal with shape (D0, ..., D{RANK-1}) and one to three dimensions. The transform extent must be even, and the element type must be float32 or float64.

  • axis (int) – Transform dimension. Negative values count from the last transform dimension.

  • complex_layout (str) – Output storage layout. Only "full" is currently supported.

Returns:

Full complex spectrum with shape (D0, ..., D{RANK-1}, 2). The trailing extent stores interleaved real and imaginary components.

Return type:

cuda.tile.Tile

nvmath.tile.fft.irfft(x, axis, complex_layout)#

Compute an unnormalized inverse complex-to-real transform.

irfft(rfft(x)) equals N * x, where N is the transform extent.

Parameters:
  • x (cuda.tile.Tile) – Full complex spectrum with shape (D0, ..., D{RANK-1}, 2) as returned by rfft(), with one to three logical dimensions.

  • axis (int) – Logical transform dimension. Negative values count from the last transform dimension.

  • complex_layout (str) – Input storage layout. Only "full" is currently supported.

Returns:

Real signal with shape (D0, ..., D{RANK-1}) after removing the trailing complex-pair extent.

Return type:

cuda.tile.Tile

class nvmath.tile.fft.FFTTileConfig(
batches_per_block: int,
num_worker_warps: int,
found: bool = True,
)#

Suggested tile configuration for an FFT of a given size, axis, rank and precision.

batches_per_block: int#

Transforms per block: the tile’s batch extent.

num_worker_warps: int#

The value for @ct.kernel(num_worker_warps=...).

found: bool#

False when the key has no suggested entry; the other fields then hold a one-batch, one-warp fallback.

nvmath.tile.fft.suggested_tile_config(
transform,
rank,
axis,
size,
precision,
arch,
*,
match='mapped_to_major_arch',
)#

Return the suggested batches_per_block and num_worker_warps for an FFT.

cfg = suggested_tile_config("fft", 1, 0, 1024, ct.float32, "sm_100")

@ct.kernel(num_worker_warps=cfg.num_worker_warps)
def kernel(...):  # tile of cfg.batches_per_block transforms
    ...
Parameters:
  • transform (str) – "fft", "ifft", "rfft" or "irfft". rfft / irfft entries exist only for the contiguous axis and cover fewer sizes.

  • rank (int) – Number of logical transform dimensions (1-3).

  • axis (int) – Logical transform dimension. Negative values count from the last one, as for fft().

  • size (int) – Transform extent along axis.

  • precision (cuda.tile.DType) – ct.float32 or ct.float64.

  • arch (str) – Target SM, in "sm_<major><minor>" form, for example, "sm_100".

  • match (str) – Architecture matching policy. Tables contain measurements for sm_80, sm_90, sm_100, and sm_120. By default ("mapped_to_major_arch"), another arch uses the tuned architecture with the same major version. For example, sm_86 and sm_89 use sm_80. sm_121 uses sm_120. A major version without a table uses sm_100. This provides a tuning starting point, not an optimum. "exact_match" suggests configurations only for architectures with their own table.

Returns:

The suggested configuration. found is false if no entry exists for this key. In that case, the other fields contain a one-batch, one-warp fallback.

Return type:

FFTTileConfig

Raises:

ValueError – For an out-of-range rank or axis, a precision other than ct.float32/ct.float64, an arch not of the form "sm_<major><minor>", or an unknown transform or match.