NVIDIA cuFFT for CUDA 12

Warnings

• breaking Deprecated GPU architectures: From CUDA 12.0 onwards, GPU architectures SM35 and SM37 are no longer supported. The minimum required architecture is SM50. Older CUDA versions (e.g., 11.0) also deprecated earlier architectures like SM30.
  Fix: Ensure your GPU hardware has a compute capability of SM50 or higher for CUDA 12.0+ applications.
• deprecated Legacy cuFFT callback functionality: Support for callback routines using separately compiled device code (legacy callbacks) has been deprecated since CUDA 11.4. CUDA Graphs capture for legacy callbacks that load data in out-of-place mode transforms is no longer supported from CUDA 11.8.
  Fix: Migrate to Link-Time Optimized (LTO) callbacks, which are supported from CUDA 12.6 Update 2 onwards, to avoid deprecation issues and leverage improved performance.
• gotcha Performance degradation with legacy callbacks: Users have reported significant performance decreases (up to 20% or more) when using legacy cuFFT callbacks in CUDA 11.8 and newer (e.g., 12.2, 12.4, 12.9+) compared to CUDA 11.7. This often manifests as increased time spent in `cuMemFree_v2` during `cufftExecC2R` or `R2C` operations.
  Fix: Consider updating to CUDA 12.6 Update 2 or newer and migrating to LTO callbacks, or investigate the performance implications for your specific callback implementations.
• gotcha Memory leak with `nvc++ -cudalib=cufft`: A potential memory leak in cuFFT library version v10.9.0.58 (shipped with CUDA 11.8) when used with `nvc++` and the `-cudalib=cufft` flag. This was linked to cuFFT failing to deallocate internal structures if the active CUDA context at program finalization was not the same used for plan creation.
  Fix: This issue was not observed in CUDA 12.0 and later. If using CUDA 11.8, ensure your CUDA context management is consistent or consider upgrading to a newer CUDA Toolkit version. Replacing `-cudalib=cufft` with `-lcufft` during compilation was also noted as a workaround.
• gotcha Interference of `cudaDeviceReset()` with `cufftPlanMany`: Calling `cudaDeviceReset()` before `cufftPlanMany` can lead to `CUFFT_INTERNAL_ERROR`. While adding `cudaSetDevice(0)` after the reset might mitigate it, `cudaDeviceReset()` is generally not recommended for regular use.
  Fix: Avoid using `cudaDeviceReset()` in critical paths before cuFFT plan creation. If absolutely necessary, re-establish the CUDA device context (e.g., with `cudaSetDevice(0)`) after `cudaDeviceReset()`.
• gotcha `CUFFT_INTERNAL_ERROR` in `cufftXtSetGPU` for multi-GPU FFTs: When performing large multi-GPU FFTs, `cufftXtSetGPU` can return an opaque 'internal error,' potentially indicating an out-of-memory condition or an unspecified library issue.
  Fix: Monitor GPU memory usage for large multi-GPU FFTs. If the error persists, consider reducing data size or reporting as a bug with NVIDIA, as 'internal error' provides limited actionable information.
• gotcha Installation timeouts/failures with concurrent downloads from `pypi.nvidia.com`: Users attempting to install `nvidia-cufft-cu12` (and other NVIDIA PyPI packages) with tools that use concurrent downloads (e.g., `uv`) may experience failures due to timeout or network issues with `pypi.nvidia.com`.
  Fix: Try setting the environment variable `UV_CONCURRENT_DOWNLOADS=1` (for `uv` users) or similar mechanisms to limit concurrent downloads when installing from `pypi.nvidia.com`.

Install

• pip install nvidia-cufft-cu12 Install via pip
• pip install nvmath-python[cu12] Install with nvmath-python (recommended for Python users)

Imports

• cuFFT functionality

  This package is a low-level runtime library and is not directly imported in Python. High-level libraries like `nvmath-python`, `torch`, or `tensorflow` provide Python interfaces that utilize `nvidia-cufft-cu12` under the hood.

  nvidia-cufft-cu12 primarily provides the underlying C/C++ binaries for GPU-accelerated FFTs. Python users typically interact with cuFFT through frameworks like PyTorch, TensorFlow, or dedicated Python wrappers like `nvmath-python`.
• nvmath.fft

  from nvmath.fft import fft, ifft

  This is the recommended way to directly access cuFFT functionalities in Python via NVIDIA's `nvmath-python` library, which depends on `nvidia-cufft-cu12`.

Quickstart

This quickstart demonstrates how to perform a 1D complex-to-complex FFT and inverse FFT using `nvmath-python`, which leverages the `nvidia-cufft-cu12` runtime library. Ensure `cupy` is also installed (it's a dependency of `nvmath-python[cu12]`) for GPU array operations.

import os
import nvmath.fft as nvfft
import cupy as cp

# Ensure CUDA is available and nvmath-python is correctly set up
# (e.g., pip install nvmath-python[cu12] and appropriate CUDA Toolkit installation)

# Example: Perform a 1D complex-to-complex FFT using nvmath-python
size = 1024
x = cp.arange(size, dtype=cp.complex64)

# Perform forward FFT
y = nvfft.fft(x)

# Perform inverse FFT
z = nvfft.ifft(y)

print(f"Original data (first 5 elements): {x[:5].tolist()}")
print(f"FFT result (first 5 elements): {y[:5].tolist()}")
print(f"Inverse FFT result (first 5 elements): {z[:5].tolist()}")
print(f"Difference from original (max abs error): {cp.max(cp.abs(x - z))}")