Summary of FFT APIs

This issue gathers all the information of the current APIs in NumPy, CuPy, Dask, JAX, MXNet, pytorch and tensorflow in the FFT module. The main outcome of this issue is to open the discussion of the potential APIs that are going to be included in the spec.

The current APIs involved in this issue are:

• Standard FFT: fft, ifft, fft2, ifft2, fftn, ifftn
• Real FFT: rfft, irfft, rfft2, irfft2, rfftn, irfftn
• Hermitian FFT: hfft, ihfft
• Helper Routines: fftfreq, rfftfreq, fftshift, ifftshift

Individual APIs

fft/ifft

argument/keyword	NumPy	CuPy	Dask	JAX	MXNet	Pytorch	TF
n	Y	Y	Y	Y	N	Y	N
axis/dim	Y	Y	Y	Y	N	Y	N
norm	Y	Y	N	Y	N	Y	N
data	N	N	N	N	Y	N	N
out	N	N	N	N	Y	N	N
name	N	N	N	N	Y	N	Y

fft2/ifft2

argument/keyword	NumPy	CuPy	Dask	JAX	Pytorch	TF
s	Y	Y	Y	Y	Y	N
axes/dim	Y	Y	Y	Y	Y	N
norm	Y	Y	N	Y	Y	N
name	N	N	N	N	N	Y

These functions are not implemented in MXNet.

fftn/ifftn

argument/keyword	NumPy	CuPy	Dask	JAX	Pytorch
n	Y	Y	N	N	Y
s	N	N	Y	Y	N
axis/axes/dim	Y	Y	Y	Y	Y
norm	Y	Y	N	Y	Y

These functions are not implemented in MXNet and TF.

rfft/irfft

argument/keyword	NumPy	CuPy	Dask	JAX	Pytorch	TF
n	Y	Y	Y	Y	Y	N
axis/dim	Y	Y	Y	Y	Y	N
norm	Y	Y	N	Y	Y	N
fft_length	N	N	N	N	N	Y
name	N	N	N	N	N	Y

These functions are not implemented in MXNet.

rfft2/irfft2

argument/keyword	NumPy	CuPy	Dask	JAX	Pytorch	TF
s	Y	Y	Y	Y	Y	N
axes/dim	Y	Y	Y	Y	Y	N
norm	Y	Y	N	Y	Y	N
fft_length	N	N	N	N	N	Y
name	N	N	N	N	N	Y

These functions are not implemented in MXNet.

rfftn/irfftn

argument/keyword	NumPy	CuPy	Dask	JAX	Pytorch
s	Y	Y	Y	Y	Y
axes/dim	Y	Y	Y	Y	Y
norm	Y	Y	N	Y	Y

These functions are not implemented in MXNet and TF.

hfft/ihfft

argument/keyword	NumPy	CuPy	Dask	JAX	Pytorch
n	Y	Y	Y	Y	Y
axis/dim	Y	Y	Y	Y	Y
norm	Y	Y	N	Y	Y

These functions are not implemented in MXNet and TF.

fftfreq/rfftfreq

argument/keyword	NumPy	CuPy	Dask	JAX	Pytorch
d	Y	Y	Y	Y	Y
dtype	N	N	N	N	Y
device	N	N	N	N	Y
requires_grad	N	N	N	N	Y
layout	N	N	N	N	Y

These functions are not implemented in MXNet and TF.

fftshift/ifftshift

argument/keyword	NumPy	CuPy	Dask	JAX	Pytorch
axes/dim	Y	Y	Y	Y	Y

These functions are not implemented in MXNet and TF.

Summary

• Most FFT APIs have the following keyword arguments: n, axis, norm, with the exception of TF and MXNet.
• The equivalent to the axis keyword in NumPy, CuPy, Dask and Jax is dim in Pytorch.
• fft2 can have the same implementation of fftn if called with the correct arguments.
• fft3D is only implemented in TF .
• The output for the inverse functions return a complex array in NumPy.
• The arguments of the functions are the same for calculating the FFT and its inverse.
• There’s a mix between the use of axis, axes even among functions in the same library.

[leofang]

3. @leofang proposed to not add fft2/ifft2 (and other 2D families), as it’s just a special case for fftn/ifftn. No one objected, but it’s best to solicit feedbacks from 3rd party libraries doing heavy imaging/signal processing.

I checked in a few libraries (SciPy, cuCIM, scikit-image, scikit-learn, matplotlib) that 2D transforms (fft2/ifft2/rfft2/irfft2) are rarely used. At most one or two places in each codebase. I believe it is fine to not include them in the standard. Perhaps they were there because in the early days libraries wanted to be compatible with Matlab? (My guess)

[rgommers]

It is of course possible to express 1-D transforms in terms of n-D, but I suspect that if we make everyone write fftn(x, 1) instead of fft(x), they won’t be too happy. I think fft is useful syntactic sugar, and it costs very little to support it.