Documentation |
Interface to FFTW library run-time algorithm tuning control
fftw('planner', method)
method = fftw('planner')
str = fftw('dwisdom')
str = fftw('swisdom')
fftw('dwisdom', str)
fftw('swisdom', str)
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 software 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 software 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. The default method is estimate:
'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 use the optimal FFT algorithm during the current MATLAB session. Reusing Optimal FFT Algorithms explains how to reuse 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', MATLAB software
Sets method to 'measure' method for FFT dimensions 8192 or smaller.
Sets method to 'estimate' for FFT dimensions greater than 8192.
method = fftw('planner') returns the current planner method.
str = fftw('dwisdom') returns the information in the FFTW library's internal double-precision database as a string. The string can be saved and then later reused in a subsequent MATLAB session using the next syntax.
str = fftw('swisdom') returns the information in the FFTW library's internal single-precision database as a string.
fftw('dwisdom', str) loads fftw wisdom represented by the string str into the FFTW library's internal double-precision wisdom database. fftw('dwisdom','') or fftw('dwisdom',[]) clears the internal wisdom database.
fftw('swisdom', str) loads fftw wisdom represented by the string str into the FFTW library's internal single-precision wisdom database. fftw('swisdom','') or fftw('swisdom',[]) clears the internal wisdom database.
Note on large powers of 2 For FFT dimensions that are powers of 2, between 2^{14} and 2^{22}, MATLAB software 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.
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, estimate.
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.000521 seconds.
If you execute the commands
tic; Y = fft(y,1458); toc Elapsed time is 0.000151 seconds.
a second time, MATLAB software reports the elapsed time as essentially 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.056532 seconds.
This tells you that it takes on order of 1/10000 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 hybrid, 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.100637 seconds.
However, the next time you call fft, it runs at approximately the same speed as before you ran the method patient.
tic;for k=1:1000 Y=fft(y,1458); end;toc Elapsed time is 0.057209 seconds.
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 a MATLAB session, load str using the command
load str
and then reload the "wisdom" into the FFTW database using the command
fftw('wisdom', str)