What does the `fft` function do in MATLAB / RunMat?

fft(X) computes the discrete Fourier transform (DFT) of the input data. When X is a vector, fft returns the frequency-domain representation of the vector. When X is a matrix or an N-D tensor, the transform is applied along the first non-singleton dimension unless another dimension is specified.

How does the `fft` function behave in MATLAB / RunMat?

fft(X) transforms along the first dimension whose size is greater than 1.
fft(X, n) zero-pads or truncates X to length n before transforming along the default dimension.
fft(X, n, dim) applies the transform along dimension dim.
Real inputs produce complex outputs; complex inputs are handled element-wise with no additional conversion.
Empty inputs remain empty; zero-padding with n produces zero-valued spectra.
GPU arrays are gathered to the host when the selected provider has no FFT implementation.

Examples of using the `fft` function in MATLAB / RunMat

Computing the FFT of a real time-domain vector

x = [1 2 3 4];
Y = fft(x);

Expected output (RunMat prints complex numbers with a + bi formatting):

Y =
  Columns 1 through 4
   10 + 0i  -2 + 2i  -2 + 0i  -2 - 2i

Applying fft column-wise to a matrix

A = [1 2 3; 4 5 6];
F = fft(A);

Expected output:

F =
   5 + 0i   7 + 0i   9 + 0i
  -3 + 3i  -3 + 3i  -3 + 3i

Zero-padding before the FFT

x = [1 2 3];
Y = fft(x, 5);

The transform is computed on a length-5 sequence [1 2 3 0 0], producing five complex frequency bins.

Selecting the transform dimension for a row vector

x = [1 2 3 4];
Y = fft(x, [], 2);

Y matches fft(x) because the transform is applied along dimension 2 (the row).

FFT of a complex-valued signal

t = 0:3;
x = exp(1i * pi/2 * t);
Y = fft(x);

The complex sinusoid is mapped to a single non-zero frequency bin at the expected location.

FFT with gpuArray inputs

g = gpuArray(rand(1, 1024));  % Residency is on the GPU
G = fft(g);                   % Falls back to host if provider FFT hooks are unavailable
result = gather(G);

RunMat gathers the data from the device and performs the transform on the host unless the active provider advertises an FFT implementation. When the WGPU provider handles the FFT, the kernel executes on the device but the result is downloaded immediately so the builtin can return a MATLAB-compatible ComplexTensor.

FAQ

Does `fft` always return complex values?

Yes. Even when the imaginary part is zero, the result is stored as a complex array to match MATLAB semantics.

What happens if I pass `[]` as the second argument?

Passing [] leaves the transform length unchanged. This is equivalent to omitting the n parameter.

Can I transform along a dimension larger than the current rank?

Yes. RunMat automatically treats trailing dimensions as length-1 and will create the requested dimension on output.

How does zero-padding work?

When n is larger than the size of X along the transform dimension, RunMat pads with zeros before evaluating the FFT.

What precision is used for the FFT?

RunMat computes FFTs in double precision on the host. Providers may use single or double precision depending on device capabilities.

Will RunMat run the FFT on my GPU automatically?

When a provider installs an FFT hook, RunMat executes on the GPU. Otherwise, the runtime gathers the data and performs the transform on the CPU.

Is inverse FFT (`ifft`) available?

ifft will be provided in a companion builtin. Until then, you can recover a time-domain signal by dividing by the length and taking the complex conjugate manually.

How do I compute multi-dimensional FFTs?

Call fft repeatedly along each dimension (fft(fft(X, [], 1), [], 2) for a 2-D FFT). Future releases will add dedicated helpers.

Does `fft` support complex strides or non-unit sampling intervals?

fft assumes unit spacing. You can multiply the result by appropriate phase factors to account for custom sampling intervals.

Source & Feedback

Full source: crates/runmat-runtime/src/builtins/math/fft/fft.rs
Found an issue? Open a ticket with a minimal reproduction.

What does the fft function do in MATLAB / RunMat?

How does the fft function behave in MATLAB / RunMat?

Examples of using the fft function in MATLAB / RunMat