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