What does the ifft function do in MATLAB / RunMat?

ifft(X) performs the inverse discrete Fourier transform (IDFT) of the data in X. For vectors, the result is a time-domain sequence whose FFT equals the original input. For matrices and higher-rank tensors, the transform is applied along the first non-singleton dimension unless a different dimension is specified.

How does the ifft function behave in MATLAB / RunMat?

• ifft(X) transforms along the first dimension whose size is greater than 1.
• ifft(X, N) zero-pads or truncates X to length N before applying the transform.
• ifft(X, N, DIM) applies the transform along dimension DIM.
• ifft(X, [], DIM) keeps the existing length and transforms along dimension DIM.
• ifft(..., 'symmetric') forces the output to be real-valued, mirroring MATLAB's handling of conjugate-symmetric spectra.
• ifft(..., 'nonsymmetric') keeps the default complex result; it is equivalent to omitting the symmetry flag but is accepted for MATLAB compatibility.
• Empty inputs and dimensions larger than the rank of X mirror MATLAB behaviour.

ifft Function GPU Execution Behaviour

RunMat keeps gpuArray inputs on the device long enough to query the active acceleration provider for the ifft_dim hook. When the hook is present, the inverse transform executes on the device, after which RunMat immediately downloads the result to return the standard MATLAB host types. If the provider lacks that hook—or if the requested length is zero—the runtime gathers the data once, evaluates the inverse transform on the CPU via rustfft, and returns a MATLAB-compatible result.

Examples of using the ifft function in MATLAB / RunMat

Reconstructing a time-domain signal from FFT bins

Y = [10  -2+2i  -2  -2-2i];
x = ifft(Y);

Expected output:

x =
  Columns 1 through 4
       1     2     3     4

Computing ifft along a specific dimension

F = [10  14  18;
     -3+3i  -3+3i  -3+3i];
X = ifft(F, [], 1);

The result matches the original two-row matrix that produced F via fft:

X =
   1 + 0i   2 + 0i   3 + 0i
   4 + 0i   5 + 0i   6 + 0i

Zero-padding the inverse transform

F = [4 0 0 0];
x = ifft(F, 8);

x has length 8, and every element equals 0.5 because only the DC bin is populated:

x =
  Columns 1 through 8
    0.5    0.5    0.5    0.5    0.5    0.5    0.5    0.5

Enforcing a real result with 'symmetric'

F = fft([1 2 3 4]);
x = ifft(F, 'symmetric');

x is returned as a real vector, discarding tiny imaginary components from numerical error.

x =
  Columns 1 through 4
       1     2     3     4

Running ifft on gpuArray inputs

G = gpuArray(fft([1 0 0 0]));
X = ifft(G);
result = gather(X);

result equals [1 0 0 0]. When the provider does not expose ifft_dim, RunMat gathers G, performs the inverse on the host, and returns a host array. When the hook exists, the device kernel runs first and the result is downloaded immediately so the builtin can return MATLAB host types.

GPU residency in RunMat (Do I need gpuArray?)

RunMat's auto-offload system keeps tensors on the GPU when profitable, so explicit gpuArray calls are rarely required. They remain available to mirror MATLAB workflows. When the provider lacks an inverse FFT hook, RunMat automatically gathers once, evaluates the transform on the host, and returns the result, so manual residency management is unnecessary.

FAQ

Does ifft always return complex values?

By default, yes. The 'symmetric' flag converts the result to a real array when the spectrum is conjugate-symmetric. You can also pass 'nonsymmetric' to state this default explicitly while keeping the complex result.

How does ifft scale the result?

RunMat divides by the transform length so that ifft(fft(x)) reproduces x, matching MATLAB.

Can I omit the length but specify a dimension?

Yes. Use an empty array for the length: ifft(X, [], DIM).

What happens if I request a zero length?

You receive an empty array along the selected dimension, mirroring MATLAB behaviour.

Does 'symmetric' validate conjugate symmetry?

No. Like MATLAB, RunMat assumes the spectrum is conjugate-symmetric and simply discards imaginary components.

Will RunMat run the inverse FFT on the GPU automatically?

Only when the provider exposes an inverse FFT kernel (ifft_dim). Otherwise, the runtime gathers to the host transparently.

How do I perform multi-dimensional inverse transforms?

Apply ifft sequentially along each dimension (e.g., ifft(ifft(X, [], 1), [], 2)).

See Also

fft, fftshift, ifftshift, gpuArray, gather

Source & Feedback

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