Mercurial > hg > sv-dependency-builds

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