fftw

Define method for determining FFT algorithm

Syntax

method = fftw('planner')

previous = fftw('planner',method)

fftinfo = fftw(wisdom)

previous = fftw(wisdom,fftinfo)

Description

method = fftw('planner') returns the method that the fast Fourier transform functions fft, fft2, fftn, ifft, ifft2, and ifftn use to determine a transform algorithm. The default method is 'estimate', which determines the algorithm based on the size of the data.

previous = fftw('planner',method) sets the method and optionally returns the previous method. For example, fftw('planner','measure') chooses the fastest algorithm based on the size and type of the data.

fftinfo = fftw(wisdom) returns the optimal transform parameters established in the current MATLAB^® session for the precision specified in wisdom. For example, fftinfo = fftw('dwisdom') saves the current double-precision transform parameters.

previous = fftw(wisdom,fftinfo) applies the parameters in fftinfo to the transform algorithm for the precision specified in wisdom.

Examples

Optimal Fourier Transform Workflow

The fftw function can improve the performance of Fourier transform functions by trying to optimize computation based on the size and type of the data.

Clear any existing double-precision transform parameters.

fftw('dwisdom',[]);

Set the method for optimizing Fourier transforms within the current MATLAB® session to 'measure'.

fftw('planner','measure');

Define a random vector and use the fft function to compute the Fourier transform. fft uses an algorithm that tries to optimize computation for the 500-by-1 transform. The first call to fft can be slower than normal, but subsequent calls will be significantly faster.

X = rand(500,1);
tic; fft(X); toc;

Elapsed time is 0.071496 seconds.

tic; fft(X); toc;

Elapsed time is 0.000152 seconds.

Assign the current double-precision transform algorithm parameters to the variable fftinfo for later use.

fftinfo = fftw('dwisdom');

Apply the parameter information stored in the variable fftinfo to future transform function calls.

fftw('dwisdom',fftinfo);

Input Arguments

method — Method for setting transform parameters

'estimate' (default) | 'measure' | 'patient' | 'exhaustive' | 'hybrid'

Method for setting transform parameters, specified as one of the following:

• 'estimate' — Determine a best-guess transform algorithm based on the size of problem.

• 'measure' — Find a better algorithm by computing multiple transforms and measuring the run times.

• 'patient' — Run a wider range of testing compared to 'measure', resulting in a better transform algorithm, but at the expense of higher computational cost to determine the parameters.

• 'exhaustive' — Runs all tests including ones unlikely to be optimal, resulting in the best algorithm, but with the highest computational cost to determine the parameters.

• 'hybrid' — Use a combination of 'measure' for transforms with dimension length 8192 or smaller and 'estimate' for transforms with dimension length larger than 8192.

Data Types: char | string

wisdom — Transform parameter precision

'swisdom' | 'dwisdom'

Transform parameter precision, specified as either 'swisdom' or 'dwisdom'. The option 'swisdom' specifies transform parameters for single-precision computation, and 'dwisdom' specifies parameters for double-precision computation.

Data Types: char

fftinfo — Transform parameters

character array | []

Transform parameters, specified as a character array of transform parameters returned by fftw(wisdom) or the empty array []. The empty array [] clears the database.

Data Types: char

Tips

• Transform parameters returned by fftw are most useful when saved and applied on one computer using the same version of MATLAB each session. Transferring saved parameters between computers can result in degraded performance, even if both computers have the same operating system and MATLAB version.

Algorithms

• For transform lengths that are powers of 2 between 2¹⁴ and 2²², MATLAB uses pre-loaded information from its internal database to optimize the transform computation. Tuning is not executed for exact powers of 2 unless you clear the database using the command fftw(wisdom,[]).

References

[1] FFTW (https://www.fftw.org)

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Code generation with MATLAB Coder™ supports fftw only for MEX output. For standalone C/C++ code, to select a planning method for FFT library calls, implement a getPlanMethod method in an FFT library callback class. For more information about an FFT library callback class, see coder.fftw.StandaloneFFTW3Interface (MATLAB Coder).

• In a MATLAB Function block, fftw is supported only for simulation. For C/C++ code generation, to select a planning method for FFT library calls, implement a getPlanMethod method in an FFT library callback class. For more information about an FFT library callback class, see coder.fftw.StandaloneFFTW3Interface (MATLAB Coder).

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced before R2006a