cannam@95: Next: Basic Interface, cannam@95: Previous: Data Types and Files, cannam@95: Up: FFTW Reference cannam@95:
Plans for all transform types in FFTW are stored as type
cannam@95: fftw_plan (an opaque pointer type), and are created by one of the
cannam@95: various planning routines described in the following sections.
cannam@95: An fftw_plan contains all information necessary to compute the
cannam@95: transform, including the pointers to the input and output arrays.
cannam@95:
cannam@95:
void fftw_execute(const fftw_plan plan); cannam@95:cannam@95:
cannam@95: This executes the plan, to compute the corresponding transform on
cannam@95: the arrays for which it was planned (which must still exist). The plan
cannam@95: is not modified, and fftw_execute can be called as many times as
cannam@95: desired.
cannam@95:
cannam@95:
To apply a given plan to a different array, you can use the new-array execute cannam@95: interface. See New-array Execute Functions. cannam@95: cannam@95:
fftw_execute (and equivalents) is the only function in FFTW
cannam@95: guaranteed to be thread-safe; see Thread safety.
cannam@95:
cannam@95:
This function: cannam@95:
void fftw_destroy_plan(fftw_plan plan); cannam@95:cannam@95:
deallocates the plan and all its associated data.
cannam@95:
cannam@95:
FFTW's planner saves some other persistent data, such as the cannam@95: accumulated wisdom and a list of algorithms available in the current cannam@95: configuration. If you want to deallocate all of that and reset FFTW cannam@95: to the pristine state it was in when you started your program, you can cannam@95: call: cannam@95: cannam@95:
void fftw_cleanup(void); cannam@95:cannam@95:
cannam@95: After calling fftw_cleanup, all existing plans become undefined,
cannam@95: and you should not attempt to execute them nor to destroy them. You can
cannam@95: however create and execute/destroy new plans, in which case FFTW starts
cannam@95: accumulating wisdom information again.
cannam@95:
cannam@95:
fftw_cleanup does not deallocate your plans, however. To prevent
cannam@95: memory leaks, you must still call fftw_destroy_plan before
cannam@95: executing fftw_cleanup.
cannam@95:
cannam@95:
Occasionally, it may useful to know FFTW's internal “cost” metric
cannam@95: that it uses to compare plans to one another; this cost is
cannam@95: proportional to an execution time of the plan, in undocumented units,
cannam@95: if the plan was created with the FFTW_MEASURE or other
cannam@95: timing-based options, or alternatively is a heuristic cost function
cannam@95: for FFTW_ESTIMATE plans. (The cost values of measured and
cannam@95: estimated plans are not comparable, being in different units. Also,
cannam@95: costs from different FFTW versions or the same version compiled
cannam@95: differently may not be in the same units. Plans created from wisdom
cannam@95: have a cost of 0 since no timing measurement is performed for them.
cannam@95: Finally, certain problems for which only one top-level algorithm was
cannam@95: possible may have required no measurements of the cost of the whole
cannam@95: plan, in which case fftw_cost will also return 0.) The cost
cannam@95: metric for a given plan is returned by:
cannam@95:
cannam@95:
double fftw_cost(const fftw_plan plan); cannam@95:cannam@95:
cannam@95: The following two routines are provided purely for academic purposes cannam@95: (that is, for entertainment). cannam@95: cannam@95:
void fftw_flops(const fftw_plan plan, cannam@95: double *add, double *mul, double *fma); cannam@95:cannam@95:
cannam@95: Given a plan, set add, mul, and fma to an
cannam@95: exact count of the number of floating-point additions, multiplications,
cannam@95: and fused multiply-add operations involved in the plan's execution. The
cannam@95: total number of floating-point operations (flops) is add + mul +
cannam@95: 2*fma, or add + mul + fma if the hardware supports fused
cannam@95: multiply-add instructions (although the number of FMA operations is only
cannam@95: approximate because of compiler voodoo). (The number of operations
cannam@95: should be an integer, but we use double to avoid overflowing
cannam@95: int for large transforms; the arguments are of type double
cannam@95: even for single and long-double precision versions of FFTW.)
cannam@95:
cannam@95:
void fftw_fprint_plan(const fftw_plan plan, FILE *output_file); cannam@95: void fftw_print_plan(const fftw_plan plan); cannam@95:cannam@95:
cannam@95: This outputs a “nerd-readable” representation of the plan to
cannam@95: the given file or to stdout, respectively.
cannam@95:
cannam@95:
cannam@95:
cannam@95: