FFTW 3.3.5: Using Plans

Plans for all transform types in FFTW are stored as type cannam@127: fftw_plan (an opaque pointer type), and are created by one of the cannam@127: various planning routines described in the following sections. cannam@127: cannam@127: An fftw_plan contains all information necessary to compute the cannam@127: transform, including the pointers to the input and output arrays. cannam@127:

cannam@127:

void fftw_execute(const fftw_plan plan);
cannam@127:

This executes the plan, to compute the corresponding transform on cannam@127: the arrays for which it was planned (which must still exist). The plan cannam@127: is not modified, and fftw_execute can be called as many times as cannam@127: desired. cannam@127:

To apply a given plan to a different array, you can use the new-array execute cannam@127: interface. See New-array Execute Functions. cannam@127:

fftw_execute (and equivalents) is the only function in FFTW cannam@127: guaranteed to be thread-safe; see Thread safety. cannam@127:

cannam@127:

void fftw_destroy_plan(fftw_plan plan);
cannam@127:

FFTW’s planner saves some other persistent data, such as the cannam@127: accumulated wisdom and a list of algorithms available in the current cannam@127: configuration. If you want to deallocate all of that and reset FFTW cannam@127: to the pristine state it was in when you started your program, you can cannam@127: call: cannam@127:

cannam@127:

void fftw_cleanup(void);
cannam@127:

After calling fftw_cleanup, all existing plans become undefined, cannam@127: and you should not attempt to execute them nor to destroy them. You can cannam@127: however create and execute/destroy new plans, in which case FFTW starts cannam@127: accumulating wisdom information again. cannam@127:

fftw_cleanup does not deallocate your plans, however. To prevent cannam@127: memory leaks, you must still call fftw_destroy_plan before cannam@127: executing fftw_cleanup. cannam@127:

Occasionally, it may useful to know FFTW’s internal “cost” metric cannam@127: that it uses to compare plans to one another; this cost is cannam@127: proportional to an execution time of the plan, in undocumented units, cannam@127: if the plan was created with the FFTW_MEASURE or other cannam@127: timing-based options, or alternatively is a heuristic cost function cannam@127: for FFTW_ESTIMATE plans. (The cost values of measured and cannam@127: estimated plans are not comparable, being in different units. Also, cannam@127: costs from different FFTW versions or the same version compiled cannam@127: differently may not be in the same units. Plans created from wisdom cannam@127: have a cost of 0 since no timing measurement is performed for them. cannam@127: Finally, certain problems for which only one top-level algorithm was cannam@127: possible may have required no measurements of the cost of the whole cannam@127: plan, in which case fftw_cost will also return 0.) The cost cannam@127: metric for a given plan is returned by: cannam@127:

cannam@127:

double fftw_cost(const fftw_plan plan);
cannam@127:

The following two routines are provided purely for academic purposes cannam@127: (that is, for entertainment). cannam@127:

cannam@127:

void fftw_flops(const fftw_plan plan, 
cannam@127:                 double *add, double *mul, double *fma);
cannam@127:

Given a plan, set add, mul, and fma to an cannam@127: exact count of the number of floating-point additions, multiplications, cannam@127: and fused multiply-add operations involved in the plan’s execution. The cannam@127: total number of floating-point operations (flops) is

add + mul +
cannam@127: 2*fma

, or add + mul + fma if the hardware supports fused cannam@127: multiply-add instructions (although the number of FMA operations is only cannam@127: approximate because of compiler voodoo). (The number of operations cannam@127: should be an integer, but we use double to avoid overflowing cannam@127: int for large transforms; the arguments are of type double cannam@127: even for single and long-double precision versions of FFTW.) cannam@127:

cannam@127:

void fftw_fprint_plan(const fftw_plan plan, FILE *output_file);
cannam@127: void fftw_print_plan(const fftw_plan plan);
cannam@127: char *fftw_sprint_plan(const fftw_plan plan);
cannam@127:

This outputs a “nerd-readable” representation of the plan to cannam@127: the given file, to stdout, or two a newly allocated cannam@127: NUL-terminated string (which the caller is responsible for deallocating cannam@127: with free), respectively. cannam@127:

4.2 Using Plans