What does the fft2 function do in MATLAB / RunMat?

fft2(X) computes the two-dimensional discrete Fourier transform (DFT) of X. It is equivalent to applying fft along the first dimension and then along the second dimension, preserving MATLAB’s column-major ordering and output shape semantics.

How does the fft2 function behave in MATLAB / RunMat?

• fft2(X) transforms along the first and second dimensions that have size greater than one.
• fft2(X, M, N) zero-pads or truncates X to M rows and N columns before evaluating the 2-D transform.
• fft2(X, SIZE) accepts a two-element vector (or scalar) specifying the transform lengths.
• Real inputs produce complex outputs; complex inputs are transformed element-wise with no additional conversion.
• Higher-dimensional inputs are transformed slice-by-slice across trailing dimensions, matching MATLAB behaviour.
• Empty dimensions yield empty outputs; zero padding with 0 produces a zero-sized complex tensor.
• GPU arrays execute on-device when the provider advertises the fft_dim hook; otherwise RunMat gathers the data and performs the transform on the host using rustfft.

Examples of using the fft2 function in MATLAB / RunMat

Computing the 2-D FFT of a small matrix

X = [1 2; 3 4];
Y = fft2(X);

Expected output:

Y =
    10 + 0i   -2 + 0i
    -4 + 0i    0 + 0i

Zero-padding an image patch before fft2

patch = [1 0 1; 0 1 0; 1 0 1];
F = fft2(patch, 8, 8);

F now contains an 8×8 spectrum suitable for convolution in the frequency domain.

Specifying transform lengths with a size vector

X = rand(4, 6);
F = fft2(X, [8 4]);   % pad rows to 8 and truncate columns to 4

Using fft2 on gpuArray data

G = gpuArray(rand(256, 256));
F = fft2(G);
R = gather(F);

When the active provider implements fft_dim, both passes remain on the GPU. Otherwise RunMat gathers G, executes the transform with rustfft, and returns a host-resident complex tensor.

Applying fft2 to each slice of a 3-D volume

V = rand(64, 64, 10);
spectra = fft2(V);

Each 64×64 slice along the third dimension receives its own two-dimensional FFT.

Verifying fft2 against sequential fft calls

X = rand(5, 7);
sequential = fft(fft(X, [], 1), [], 2);
direct = fft2(X);

direct and sequential produce the same complex data (up to round-off).

GPU residency in RunMat (Do I need gpuArray?)

You usually do NOT need to call gpuArray manually. The fusion planner and native acceleration layer keep tensors on the GPU when a provider offers FFT kernels. If the provider lacks fft_dim, RunMat gathers inputs, evaluates the FFT pair on the host, and returns a MATLAB-compatible complex tensor. You can still use gpuArray for explicit residency control, particularly when interoperating with MATLAB code that expects it.

FAQ

1. Is fft2(X) the same as fft(fft(X, [], 1), [], 2)?
   Yes. RunMat literally performs the two sequential transforms so the results match MATLAB exactly.

2. How do zero-length transform sizes behave?
   Passing 0 for either M or N produces a complex tensor with zero elements along that dimension.

3. Can I use a single scalar for the size argument?
   Yes. fft2(X, K) is shorthand for fft2(X, [K K]), padding or truncating both dimensions to K.

4. What happens when X has more than two dimensions?
   RunMat applies fft2 to every 2-D slice defined by the first two dimensions, leaving higher dimensions untouched.

5. Do I get complex outputs for real inputs?
   Always. Even when the imaginary parts are zero, outputs are stored as complex tensors to mirror MATLAB semantics.

6. Will fft2 run on the GPU automatically?
   Yes if the active provider implements fft_dim. Otherwise RunMat gathers to the host and performs the transform with rustfft.

7. Does fft2 normalise the output?
   No. Like MATLAB, the forward FFT leaves scaling untouched; use ifft2 for the inverse with 1/(M*N) scaling.

8. Can I mix [] with explicit sizes (e.g., fft2(X, [], 128))?
   Yes. Passing [] leaves that dimension unchanged while applying the specified size to the other dimension.

See Also

fft, ifft, fftshift, gpuArray, gather

Source & Feedback

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