Mercurial > hg > sv-dependency-builds

annotate src/fftw-3.3.3/doc/html/Using-Plans.html @ 10:37bf6b4a2645

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add FFTW3
author Chris Cannam
date Wed, 20 Mar 2013 15:35:50 +0000
parents
children
rev   line source
Chris@10 1 <html lang="en">
Chris@10 2 <head>
Chris@10 3 <title>Using Plans - FFTW 3.3.3</title>
Chris@10 4 <meta http-equiv="Content-Type" content="text/html">
Chris@10 5 <meta name="description" content="FFTW 3.3.3">
Chris@10 6 <meta name="generator" content="makeinfo 4.13">
Chris@10 7 <link title="Top" rel="start" href="index.html#Top">
Chris@10 8 <link rel="up" href="FFTW-Reference.html#FFTW-Reference" title="FFTW Reference">
Chris@10 9 <link rel="prev" href="Data-Types-and-Files.html#Data-Types-and-Files" title="Data Types and Files">
Chris@10 10 <link rel="next" href="Basic-Interface.html#Basic-Interface" title="Basic Interface">
Chris@10 11 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
Chris@10 12 <!--
Chris@10 13 This manual is for FFTW
Chris@10 14 (version 3.3.3, 25 November 2012).
Chris@10 15
Chris@10 16 Copyright (C) 2003 Matteo Frigo.
Chris@10 17
Chris@10 18 Copyright (C) 2003 Massachusetts Institute of Technology.
Chris@10 19
Chris@10 20 Permission is granted to make and distribute verbatim copies of
Chris@10 21 this manual provided the copyright notice and this permission
Chris@10 22 notice are preserved on all copies.
Chris@10 23
Chris@10 24 Permission is granted to copy and distribute modified versions of
Chris@10 25 this manual under the conditions for verbatim copying, provided
Chris@10 26 that the entire resulting derived work is distributed under the
Chris@10 27 terms of a permission notice identical to this one.
Chris@10 28
Chris@10 29 Permission is granted to copy and distribute translations of this
Chris@10 30 manual into another language, under the above conditions for
Chris@10 31 modified versions, except that this permission notice may be
Chris@10 32 stated in a translation approved by the Free Software Foundation.
Chris@10 33 -->
Chris@10 34 <meta http-equiv="Content-Style-Type" content="text/css">
Chris@10 35 <style type="text/css"><!--
Chris@10 36 pre.display { font-family:inherit }
Chris@10 37 pre.format { font-family:inherit }
Chris@10 38 pre.smalldisplay { font-family:inherit; font-size:smaller }
Chris@10 39 pre.smallformat { font-family:inherit; font-size:smaller }
Chris@10 40 pre.smallexample { font-size:smaller }
Chris@10 41 pre.smalllisp { font-size:smaller }
Chris@10 42 span.sc { font-variant:small-caps }
Chris@10 43 span.roman { font-family:serif; font-weight:normal; }
Chris@10 44 span.sansserif { font-family:sans-serif; font-weight:normal; }
Chris@10 45 --></style>
Chris@10 46 </head>
Chris@10 47 <body>
Chris@10 48 <div class="node">
Chris@10 49 <a name="Using-Plans"></a>
Chris@10 50 <p>
Chris@10 51 Next:&nbsp;<a rel="next" accesskey="n" href="Basic-Interface.html#Basic-Interface">Basic Interface</a>,
Chris@10 52 Previous:&nbsp;<a rel="previous" accesskey="p" href="Data-Types-and-Files.html#Data-Types-and-Files">Data Types and Files</a>,
Chris@10 53 Up:&nbsp;<a rel="up" accesskey="u" href="FFTW-Reference.html#FFTW-Reference">FFTW Reference</a>
Chris@10 54 <hr>
Chris@10 55 </div>
Chris@10 56
Chris@10 57 <h3 class="section">4.2 Using Plans</h3>
Chris@10 58
Chris@10 59 <p>Plans for all transform types in FFTW are stored as type
Chris@10 60 <code>fftw_plan</code> (an opaque pointer type), and are created by one of the
Chris@10 61 various planning routines described in the following sections.
Chris@10 62 <a name="index-fftw_005fplan-152"></a>An <code>fftw_plan</code> contains all information necessary to compute the
Chris@10 63 transform, including the pointers to the input and output arrays.
Chris@10 64
Chris@10 65 <pre class="example"> void fftw_execute(const fftw_plan plan);
Chris@10 66 </pre>
Chris@10 67 <p><a name="index-fftw_005fexecute-153"></a>
Chris@10 68 This executes the <code>plan</code>, to compute the corresponding transform on
Chris@10 69 the arrays for which it was planned (which must still exist). The plan
Chris@10 70 is not modified, and <code>fftw_execute</code> can be called as many times as
Chris@10 71 desired.
Chris@10 72
Chris@10 73 <p>To apply a given plan to a different array, you can use the new-array execute
Chris@10 74 interface. See <a href="New_002darray-Execute-Functions.html#New_002darray-Execute-Functions">New-array Execute Functions</a>.
Chris@10 75
Chris@10 76 <p><code>fftw_execute</code> (and equivalents) is the only function in FFTW
Chris@10 77 guaranteed to be thread-safe; see <a href="Thread-safety.html#Thread-safety">Thread safety</a>.
Chris@10 78
Chris@10 79 <p>This function:
Chris@10 80 <pre class="example"> void fftw_destroy_plan(fftw_plan plan);
Chris@10 81 </pre>
Chris@10 82 <p><a name="index-fftw_005fdestroy_005fplan-154"></a>deallocates the <code>plan</code> and all its associated data.
Chris@10 83
Chris@10 84 <p>FFTW's planner saves some other persistent data, such as the
Chris@10 85 accumulated wisdom and a list of algorithms available in the current
Chris@10 86 configuration. If you want to deallocate all of that and reset FFTW
Chris@10 87 to the pristine state it was in when you started your program, you can
Chris@10 88 call:
Chris@10 89
Chris@10 90 <pre class="example"> void fftw_cleanup(void);
Chris@10 91 </pre>
Chris@10 92 <p><a name="index-fftw_005fcleanup-155"></a>
Chris@10 93 After calling <code>fftw_cleanup</code>, all existing plans become undefined,
Chris@10 94 and you should not attempt to execute them nor to destroy them. You can
Chris@10 95 however create and execute/destroy new plans, in which case FFTW starts
Chris@10 96 accumulating wisdom information again.
Chris@10 97
Chris@10 98 <p><code>fftw_cleanup</code> does not deallocate your plans, however. To prevent
Chris@10 99 memory leaks, you must still call <code>fftw_destroy_plan</code> before
Chris@10 100 executing <code>fftw_cleanup</code>.
Chris@10 101
Chris@10 102 <p>Occasionally, it may useful to know FFTW's internal &ldquo;cost&rdquo; metric
Chris@10 103 that it uses to compare plans to one another; this cost is
Chris@10 104 proportional to an execution time of the plan, in undocumented units,
Chris@10 105 if the plan was created with the <code>FFTW_MEASURE</code> or other
Chris@10 106 timing-based options, or alternatively is a heuristic cost function
Chris@10 107 for <code>FFTW_ESTIMATE</code> plans. (The cost values of measured and
Chris@10 108 estimated plans are not comparable, being in different units. Also,
Chris@10 109 costs from different FFTW versions or the same version compiled
Chris@10 110 differently may not be in the same units. Plans created from wisdom
Chris@10 111 have a cost of 0 since no timing measurement is performed for them.
Chris@10 112 Finally, certain problems for which only one top-level algorithm was
Chris@10 113 possible may have required no measurements of the cost of the whole
Chris@10 114 plan, in which case <code>fftw_cost</code> will also return 0.) The cost
Chris@10 115 metric for a given plan is returned by:
Chris@10 116
Chris@10 117 <pre class="example"> double fftw_cost(const fftw_plan plan);
Chris@10 118 </pre>
Chris@10 119 <p><a name="index-fftw_005fcost-156"></a>
Chris@10 120 The following two routines are provided purely for academic purposes
Chris@10 121 (that is, for entertainment).
Chris@10 122
Chris@10 123 <pre class="example"> void fftw_flops(const fftw_plan plan,
Chris@10 124 double *add, double *mul, double *fma);
Chris@10 125 </pre>
Chris@10 126 <p><a name="index-fftw_005fflops-157"></a>
Chris@10 127 Given a <code>plan</code>, set <code>add</code>, <code>mul</code>, and <code>fma</code> to an
Chris@10 128 exact count of the number of floating-point additions, multiplications,
Chris@10 129 and fused multiply-add operations involved in the plan's execution. The
Chris@10 130 total number of floating-point operations (flops) is <code>add + mul +
Chris@10 131 2*fma</code>, or <code>add + mul + fma</code> if the hardware supports fused
Chris@10 132 multiply-add instructions (although the number of FMA operations is only
Chris@10 133 approximate because of compiler voodoo). (The number of operations
Chris@10 134 should be an integer, but we use <code>double</code> to avoid overflowing
Chris@10 135 <code>int</code> for large transforms; the arguments are of type <code>double</code>
Chris@10 136 even for single and long-double precision versions of FFTW.)
Chris@10 137
Chris@10 138 <pre class="example"> void fftw_fprint_plan(const fftw_plan plan, FILE *output_file);
Chris@10 139 void fftw_print_plan(const fftw_plan plan);
Chris@10 140 </pre>
Chris@10 141 <p><a name="index-fftw_005ffprint_005fplan-158"></a><a name="index-fftw_005fprint_005fplan-159"></a>
Chris@10 142 This outputs a &ldquo;nerd-readable&rdquo; representation of the <code>plan</code> to
Chris@10 143 the given file or to <code>stdout</code>, respectively.
Chris@10 144
Chris@10 145 <!-- -->
Chris@10 146 </body></html>
Chris@10 147