fftw (MATLAB Functions)

Interface to the FFTW library run-time algorithm for tuning fast Fourier transform (FFT) computations

Syntax

fftw('planner', method)
method = fftw('planner')
str = fftw('wisdom')
fftw('wisdom', str) 
fftw('wisdom', '')
fftw('wisdom', [])

Description

fftw enables you to optimize the speed of the MATLAB FFT functions fft, ifft, fft2, ifft2, fftn, and ifftn. You can use fftw to set options for a tuning algorithm that experimentally determines the fastest algorithm for computing an FFT of a particular size and dimension at run time. MATLAB records the optimal algorithm in an internal data base and uses it to compute FFTs of the same size throughout the current session. The tuning algorithm is part of the FFTW library that MATLAB uses to compute FFTs.

fftw('planner', method) sets the method by which the tuning algorithm searches for a good FFT algorithm when the dimension of the FFT is not a power of 2. You can specify method to be one of the following:

'estimate'
'measure'
'patient'
'exhaustive'
'hybrid'

When you call fftw('planner', method), the next time you call one of the FFT functions, such as fft, the tuning algorithm uses the specified method to optimize the FFT computation. Because the tuning involves trying different algorithms, the first time you call an FFT function, it might run more slowly than if you did not call fftw. However, subsequent calls to any of the FFT functions, for a problem of the same size, often run more quickly than they would without using fftw.

Note The FFT functions only uses the optimal FFT algorithm during the current MATLAB session. Reusing Optimal FFT Algorithms explains how to ruse the optimal algorithm in a future MATLAB session.

If you set the method to 'estimate', the FFTW library does not use run-time tuning to select the algorithms. The resulting algorithms might not be optimal.

If you set the method to 'measure', the FFTW library experiments with many different algorithms to compute an FFT of a given size and chooses the fastest. Setting the method to 'patient' or 'exhaustive' has a similar result, but the library experiments with even more algorithms so that the tuning takes longer the first time you call an FFT function. However, subsequent calls to FFT functions are faster than with 'measure'.

If you set 'planner' to 'hybrid', the default method, MATLAB

Sets method to 'measure' method for FFT dimensions 8192 or smaller.
Sets method to 'estimate' for FFT dimensions greater than 8192.

The following table compares the run times off the FFT functions for the different methods

Method
First Run of FFT Function
Subsequent Runs of FFT Function

'estimate'
Fastest
Slowest

'measure'
Faster
Slower

'patient'
Slower
Faster

'exhaustive'
Slowest
Fastest

Method	First Run of FFT Function	Subsequent Runs of FFT Function
`'estimate'`	Fastest	Slowest
`'measure'`	Faster	Slower
`'patient'`	Slower	Faster
`'exhaustive'`	Slowest	Fastest

method = fftw('planner') returns the current planner method.

str = fftw('wisdom') returns the information in the FFTW library's internal database, called "wisdom," as a string. The string can be saved and then later reused in a subsequent MATLAB session using the next syntax.

fftw('wisdom', str) loads the string str, containing FFTW wisdom, into the FFTW library's internal wisdom database.

fftw('wisdom','') or fftw('wisdom',[]) clears the internal wisdom database.

Note on large powers of 2 For FFT dimensions that are powers of 2, between 2¹⁴ and 2²², MATLAB uses special preloaded information in its internal database to optimize the FFT computation. No tuning is performed when the dimension of the FTT is a power of 2, unless you clear the database using the command fftw('wisdom', []).

For more information about the FFTW library, see http://www.fftw.org.

Example

Comparison of Speed for Different Planner Methods

The following example illustrates the run times for different settings of 'planner'. The example first creates some data and applies fft to it using the default method 'hybrid'. Since the dimension of the FFT is 1458, which is less than 8192, 'hybrid' uses the same method as 'measure'.

t=0:.001:5;
x = sin(2*pi*50*t)+sin(2*pi*120*t);
y = x + 2*randn(size(t));
tic; Y = fft(y,1458); toc
Elapsed time is 0.030000 seconds.

If you execute the commands

```
tic; Y = fft(y,1458); toc
```

a second time, MATLAB reports the elapsed time as 0. To measure the elapsed time more accurately, you can execute the command Y = fft(y,1458) 1000 times in a loop.

tic; for k=1:1000
Y = fft(y,1458);
end; toc
Elapsed time is 0.911000 seconds.

This tells you that it takes approximately 1/1000 of a second to execute fft(y, 1458) a single time.

For comparison, set 'planner' to 'patient'. Since this 'planner' explores possible algorithms more thoroughly than 'patient', the first time you run fft, it takes longer to compute the results.

fftw('planner','patient')
tic;Y = fft(y,1458);toc
Elapsed time is 0.130000 seconds.

However, the next time you call fft, it runs approximately 10 times faster than it when you use the method 'measure'.

tic;for k=1:1000
Y=fft(y,1458);
end;toc
Elapsed time is 0.080000 seconds.

Reusing Optimal FFT Algorithms

In order to use the optimized FFT algorithm in a future MATLAB session, first save the "wisdom" using the command

```
str = fftw('wisdom')
```

You can save str for a future session using the command

```
save str
```

The next time you open MATLAB, load str using the command

```
load str
```

and then reload the "wisdom" into the FFTW database using the command

```
fftw('wisdom', str)
```

See Also

fft, fft2, fftn, ifft, ifft2, ifftn, fftshift.

fftshift fgetl