Chris@19: Chris@19: Chris@19: Using Plans - FFTW 3.3.4 Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19:
Chris@19: Chris@19:

Chris@19: Next: , Chris@19: Previous: Data Types and Files, Chris@19: Up: FFTW Reference Chris@19:


Chris@19:
Chris@19: Chris@19:

4.2 Using Plans

Chris@19: Chris@19:

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

     void fftw_execute(const fftw_plan plan);
Chris@19: 
Chris@19:

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

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

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

This function: Chris@19:

     void fftw_destroy_plan(fftw_plan plan);
Chris@19: 
Chris@19:

deallocates the plan and all its associated data. Chris@19: Chris@19:

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

     void fftw_cleanup(void);
Chris@19: 
Chris@19:

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

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

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

     double fftw_cost(const fftw_plan plan);
Chris@19: 
Chris@19:

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

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

Chris@19: Given a plan, set add, mul, and fma to an Chris@19: exact count of the number of floating-point additions, multiplications, Chris@19: and fused multiply-add operations involved in the plan's execution. The Chris@19: total number of floating-point operations (flops) is add + mul + Chris@19: 2*fma, or add + mul + fma if the hardware supports fused Chris@19: multiply-add instructions (although the number of FMA operations is only Chris@19: approximate because of compiler voodoo). (The number of operations Chris@19: should be an integer, but we use double to avoid overflowing Chris@19: int for large transforms; the arguments are of type double Chris@19: even for single and long-double precision versions of FFTW.) Chris@19: Chris@19:

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

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