fftw3: Planner Flags
4.3.2 Planner Flags
-------------------
All of the planner routines in FFTW accept an integer 'flags' argument,
which is a bitwise OR ('|') of zero or more of the flag constants
defined below. These flags control the rigor (and time) of the planning
process, and can also impose (or lift) restrictions on the type of
transform algorithm that is employed.
_Important:_ the planner overwrites the input array during planning
unless a saved plan (
Wisdom) is available for that problem, so
you should initialize your input data after creating the plan. The only
exceptions to this are the 'FFTW_ESTIMATE' and 'FFTW_WISDOM_ONLY' flags,
as mentioned below.
In all cases, if wisdom is available for the given problem that was
created with equal-or-greater planning rigor, then the more rigorous
wisdom is used. For example, in 'FFTW_ESTIMATE' mode any available
wisdom is used, whereas in 'FFTW_PATIENT' mode only wisdom created in
patient or exhaustive mode can be used. Words of Wisdom-Saving
Plans.
Planning-rigor flags
....................
* 'FFTW_ESTIMATE' specifies that, instead of actual measurements of
different algorithms, a simple heuristic is used to pick a
(probably sub-optimal) plan quickly. With this flag, the
input/output arrays are not overwritten during planning.
* 'FFTW_MEASURE' tells FFTW to find an optimized plan by actually
_computing_ several FFTs and measuring their execution time.
Depending on your machine, this can take some time (often a few
seconds). 'FFTW_MEASURE' is the default planning option.
* 'FFTW_PATIENT' is like 'FFTW_MEASURE', but considers a wider range
of algorithms and often produces a "more optimal" plan (especially
for large transforms), but at the expense of several times longer
planning time (especially for large transforms).
* 'FFTW_EXHAUSTIVE' is like 'FFTW_PATIENT', but considers an even
wider range of algorithms, including many that we think are
unlikely to be fast, to produce the most optimal plan but with a
substantially increased planning time.
* 'FFTW_WISDOM_ONLY' is a special planning mode in which the plan is
only created if wisdom is available for the given problem, and
otherwise a 'NULL' plan is returned. This can be combined with
other flags, e.g. 'FFTW_WISDOM_ONLY | FFTW_PATIENT' creates a plan
only if wisdom is available that was created in 'FFTW_PATIENT' or
'FFTW_EXHAUSTIVE' mode. The 'FFTW_WISDOM_ONLY' flag is intended
for users who need to detect whether wisdom is available; for
example, if wisdom is not available one may wish to allocate new
arrays for planning so that user data is not overwritten.
Algorithm-restriction flags
...........................
* 'FFTW_DESTROY_INPUT' specifies that an out-of-place transform is
allowed to _overwrite its input_ array with arbitrary data; this
can sometimes allow more efficient algorithms to be employed.
* 'FFTW_PRESERVE_INPUT' specifies that an out-of-place transform must
_not change its input_ array. This is ordinarily the _default_,
except for c2r and hc2r (i.e. complex-to-real) transforms for
which 'FFTW_DESTROY_INPUT' is the default. In the latter cases,
passing 'FFTW_PRESERVE_INPUT' will attempt to use algorithms that
do not destroy the input, at the expense of worse performance; for
multi-dimensional c2r transforms, however, no input-preserving
algorithms are implemented and the planner will return 'NULL' if
one is requested.
* 'FFTW_UNALIGNED' specifies that the algorithm may not impose any
unusual alignment requirements on the input/output arrays (i.e. no
SIMD may be used). This flag is normally _not necessary_, since
the planner automatically detects misaligned arrays. The only use
for this flag is if you want to use the new-array execute interface
to execute a given plan on a different array that may not be
aligned like the original. (Using 'fftw_malloc' makes this flag
unnecessary even then. You can also use 'fftw_alignment_of' to
detect whether two arrays are equivalently aligned.)
Limiting planning time
......................
extern void fftw_set_timelimit(double seconds);
This function instructs FFTW to spend at most 'seconds' seconds
(approximately) in the planner. If 'seconds == FFTW_NO_TIMELIMIT' (the
default value, which is negative), then planning time is unbounded.
Otherwise, FFTW plans with a progressively wider range of algorithms
until the the given time limit is reached or the given range of
algorithms is explored, returning the best available plan.
For example, specifying 'FFTW_PATIENT' first plans in 'FFTW_ESTIMATE'
mode, then in 'FFTW_MEASURE' mode, then finally (time permitting) in
'FFTW_PATIENT'. If 'FFTW_EXHAUSTIVE' is specified instead, the planner
will further progress to 'FFTW_EXHAUSTIVE' mode.
Note that the 'seconds' argument specifies only a rough limit; in
practice, the planner may use somewhat more time if the time limit is
reached when the planner is in the middle of an operation that cannot be
interrupted. At the very least, the planner will complete planning in
'FFTW_ESTIMATE' mode (which is thus equivalent to a time limit of 0).
Info Catalog
fftw3: Complex DFTs
fftw3: Basic Interface
fftw3: Real-data DFTs