cannam@95: <html lang="en">
cannam@95: <head>
cannam@95: <title>Using Plans - FFTW 3.3.3</title>
cannam@95: <meta http-equiv="Content-Type" content="text/html">
cannam@95: <meta name="description" content="FFTW 3.3.3">
cannam@95: <meta name="generator" content="makeinfo 4.13">
cannam@95: <link title="Top" rel="start" href="index.html#Top">
cannam@95: <link rel="up" href="FFTW-Reference.html#FFTW-Reference" title="FFTW Reference">
cannam@95: <link rel="prev" href="Data-Types-and-Files.html#Data-Types-and-Files" title="Data Types and Files">
cannam@95: <link rel="next" href="Basic-Interface.html#Basic-Interface" title="Basic Interface">
cannam@95: <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
cannam@95: <!--
cannam@95: This manual is for FFTW
cannam@95: (version 3.3.3, 25 November 2012).
cannam@95:
cannam@95: Copyright (C) 2003 Matteo Frigo.
cannam@95:
cannam@95: Copyright (C) 2003 Massachusetts Institute of Technology.
cannam@95:
cannam@95: Permission is granted to make and distribute verbatim copies of
cannam@95: this manual provided the copyright notice and this permission
cannam@95: notice are preserved on all copies.
cannam@95:
cannam@95: Permission is granted to copy and distribute modified versions of
cannam@95: this manual under the conditions for verbatim copying, provided
cannam@95: that the entire resulting derived work is distributed under the
cannam@95: terms of a permission notice identical to this one.
cannam@95:
cannam@95: Permission is granted to copy and distribute translations of this
cannam@95: manual into another language, under the above conditions for
cannam@95: modified versions, except that this permission notice may be
cannam@95: stated in a translation approved by the Free Software Foundation.
cannam@95: -->
cannam@95: <meta http-equiv="Content-Style-Type" content="text/css">
cannam@95: <style type="text/css"><!--
cannam@95: pre.display { font-family:inherit }
cannam@95: pre.format { font-family:inherit }
cannam@95: pre.smalldisplay { font-family:inherit; font-size:smaller }
cannam@95: pre.smallformat { font-family:inherit; font-size:smaller }
cannam@95: pre.smallexample { font-size:smaller }
cannam@95: pre.smalllisp { font-size:smaller }
cannam@95: span.sc { font-variant:small-caps }
cannam@95: span.roman { font-family:serif; font-weight:normal; }
cannam@95: span.sansserif { font-family:sans-serif; font-weight:normal; }
cannam@95: --></style>
cannam@95: </head>
cannam@95: <body>
cannam@95: <div class="node">
cannam@95: <a name="Using-Plans"></a>
cannam@95: <p>
cannam@95: Next: <a rel="next" accesskey="n" href="Basic-Interface.html#Basic-Interface">Basic Interface</a>,
cannam@95: Previous: <a rel="previous" accesskey="p" href="Data-Types-and-Files.html#Data-Types-and-Files">Data Types and Files</a>,
cannam@95: Up: <a rel="up" accesskey="u" href="FFTW-Reference.html#FFTW-Reference">FFTW Reference</a>
cannam@95: <hr>
cannam@95: </div>
cannam@95:
cannam@95: <h3 class="section">4.2 Using Plans</h3>
cannam@95:
cannam@95: <p>Plans for all transform types in FFTW are stored as type
cannam@95: <code>fftw_plan</code> (an opaque pointer type), and are created by one of the
cannam@95: various planning routines described in the following sections.
cannam@95: <a name="index-fftw_005fplan-152"></a>An <code>fftw_plan</code> contains all information necessary to compute the
cannam@95: transform, including the pointers to the input and output arrays.
cannam@95:
cannam@95: <pre class="example"> void fftw_execute(const fftw_plan plan);
cannam@95: </pre>
cannam@95: <p><a name="index-fftw_005fexecute-153"></a>
cannam@95: This executes the <code>plan</code>, 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 <code>fftw_execute</code> can be called as many times as
cannam@95: desired.
cannam@95:
cannam@95: <p>To apply a given plan to a different array, you can use the new-array execute
cannam@95: interface. See <a href="New_002darray-Execute-Functions.html#New_002darray-Execute-Functions">New-array Execute Functions</a>.
cannam@95:
cannam@95: <p><code>fftw_execute</code> (and equivalents) is the only function in FFTW
cannam@95: guaranteed to be thread-safe; see <a href="Thread-safety.html#Thread-safety">Thread safety</a>.
cannam@95:
cannam@95: <p>This function:
cannam@95: <pre class="example"> void fftw_destroy_plan(fftw_plan plan);
cannam@95: </pre>
cannam@95: <p><a name="index-fftw_005fdestroy_005fplan-154"></a>deallocates the <code>plan</code> and all its associated data.
cannam@95:
cannam@95: <p>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: <pre class="example"> void fftw_cleanup(void);
cannam@95: </pre>
cannam@95: <p><a name="index-fftw_005fcleanup-155"></a>
cannam@95: After calling <code>fftw_cleanup</code>, 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: <p><code>fftw_cleanup</code> does not deallocate your plans, however. To prevent
cannam@95: memory leaks, you must still call <code>fftw_destroy_plan</code> before
cannam@95: executing <code>fftw_cleanup</code>.
cannam@95:
cannam@95: <p>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 <code>FFTW_MEASURE</code> or other
cannam@95: timing-based options, or alternatively is a heuristic cost function
cannam@95: for <code>FFTW_ESTIMATE</code> 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 <code>fftw_cost</code> will also return 0.) The cost
cannam@95: metric for a given plan is returned by:
cannam@95:
cannam@95: <pre class="example"> double fftw_cost(const fftw_plan plan);
cannam@95: </pre>
cannam@95: <p><a name="index-fftw_005fcost-156"></a>
cannam@95: The following two routines are provided purely for academic purposes
cannam@95: (that is, for entertainment).
cannam@95:
cannam@95: <pre class="example"> void fftw_flops(const fftw_plan plan,
cannam@95: double *add, double *mul, double *fma);
cannam@95: </pre>
cannam@95: <p><a name="index-fftw_005fflops-157"></a>
cannam@95: Given a <code>plan</code>, set <code>add</code>, <code>mul</code>, and <code>fma</code> 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 <code>add + mul +
cannam@95: 2*fma</code>, or <code>add + mul + fma</code> 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 <code>double</code> to avoid overflowing
cannam@95: <code>int</code> for large transforms; the arguments are of type <code>double</code>
cannam@95: even for single and long-double precision versions of FFTW.)
cannam@95:
cannam@95: <pre class="example"> void fftw_fprint_plan(const fftw_plan plan, FILE *output_file);
cannam@95: void fftw_print_plan(const fftw_plan plan);
cannam@95: </pre>
cannam@95: <p><a name="index-fftw_005ffprint_005fplan-158"></a><a name="index-fftw_005fprint_005fplan-159"></a>
cannam@95: This outputs a “nerd-readable” representation of the <code>plan</code> to
cannam@95: the given file or to <code>stdout</code>, respectively.
cannam@95:
cannam@95: <!-- -->
cannam@95: </body></html>
cannam@95: