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