Mercurial > hg > sv-dependency-builds

comparison src/fftw-3.3.3/doc/html/Planner-Flags.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>Planner Flags - 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="Basic-Interface.html#Basic-Interface" title="Basic Interface">
9 <link rel="prev" href="Complex-DFTs.html#Complex-DFTs" title="Complex DFTs">
10 <link rel="next" href="Real_002ddata-DFTs.html#Real_002ddata-DFTs" title="Real-data DFTs">
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="Planner-Flags"></a>
50 <p>
51 Next:&nbsp;<a rel="next" accesskey="n" href="Real_002ddata-DFTs.html#Real_002ddata-DFTs">Real-data DFTs</a>,
52 Previous:&nbsp;<a rel="previous" accesskey="p" href="Complex-DFTs.html#Complex-DFTs">Complex DFTs</a>,
53 Up:&nbsp;<a rel="up" accesskey="u" href="Basic-Interface.html#Basic-Interface">Basic Interface</a>
54 <hr>
55 </div>
56
57 <h4 class="subsection">4.3.2 Planner Flags</h4>
58
59 <p>All of the planner routines in FFTW accept an integer <code>flags</code>
60 argument, which is a bitwise OR (&lsquo;<samp><span class="samp">|</span></samp>&rsquo;) of zero or more of the flag
61 constants defined below. These flags control the rigor (and time) of
62 the planning process, and can also impose (or lift) restrictions on the
63 type of transform algorithm that is employed.
64
65 <p><em>Important:</em> the planner overwrites the input array during
66 planning unless a saved plan (see <a href="Wisdom.html#Wisdom">Wisdom</a>) is available for that
67 problem, so you should initialize your input data after creating the
68 plan. The only exceptions to this are the <code>FFTW_ESTIMATE</code> and
69 <code>FFTW_WISDOM_ONLY</code> flags, as mentioned below.
70
71 <p>In all cases, if wisdom is available for the given problem that was
72 created with equal-or-greater planning rigor, then the more rigorous
73 wisdom is used. For example, in <code>FFTW_ESTIMATE</code> mode any available
74 wisdom is used, whereas in <code>FFTW_PATIENT</code> mode only wisdom created
75 in patient or exhaustive mode can be used. See <a href="Words-of-Wisdom_002dSaving-Plans.html#Words-of-Wisdom_002dSaving-Plans">Words of Wisdom-Saving Plans</a>.
76
77 <h5 class="subsubheading">Planning-rigor flags</h5>
78
79 <ul>
80 <li><a name="index-FFTW_005fESTIMATE-171"></a><code>FFTW_ESTIMATE</code> specifies that, instead of actual measurements of
81 different algorithms, a simple heuristic is used to pick a (probably
82 sub-optimal) plan quickly. With this flag, the input/output arrays are
83 not overwritten during planning.
84
85 <li><a name="index-FFTW_005fMEASURE-172"></a><code>FFTW_MEASURE</code> tells FFTW to find an optimized plan by actually
86 <em>computing</em> several FFTs and measuring their execution time.
87 Depending on your machine, this can take some time (often a few
88 seconds). <code>FFTW_MEASURE</code> is the default planning option.
89
90 <li><a name="index-FFTW_005fPATIENT-173"></a><code>FFTW_PATIENT</code> is like <code>FFTW_MEASURE</code>, but considers a wider
91 range of algorithms and often produces a &ldquo;more optimal&rdquo; plan
92 (especially for large transforms), but at the expense of several times
93 longer planning time (especially for large transforms).
94
95 <li><a name="index-FFTW_005fEXHAUSTIVE-174"></a><code>FFTW_EXHAUSTIVE</code> is like <code>FFTW_PATIENT</code>, but considers an
96 even wider range of algorithms, including many that we think are
97 unlikely to be fast, to produce the most optimal plan but with a
98 substantially increased planning time.
99
100 <li><a name="index-FFTW_005fWISDOM_005fONLY-175"></a><code>FFTW_WISDOM_ONLY</code> is a special planning mode in which the plan
101 is only created if wisdom is available for the given problem, and
102 otherwise a <code>NULL</code> plan is returned. This can be combined with
103 other flags, e.g. &lsquo;<samp><span class="samp">FFTW_WISDOM_ONLY | FFTW_PATIENT</span></samp>&rsquo; creates a
104 plan only if wisdom is available that was created in
105 <code>FFTW_PATIENT</code> or <code>FFTW_EXHAUSTIVE</code> mode. The
106 <code>FFTW_WISDOM_ONLY</code> flag is intended for users who need to detect
107 whether wisdom is available; for example, if wisdom is not available
108 one may wish to allocate new arrays for planning so that user data is
109 not overwritten.
110
111 </ul>
112
113 <h5 class="subsubheading">Algorithm-restriction flags</h5>
114
115 <ul>
116 <li><a name="index-FFTW_005fDESTROY_005fINPUT-176"></a><code>FFTW_DESTROY_INPUT</code> specifies that an out-of-place transform is
117 allowed to <em>overwrite its input</em> array with arbitrary data; this
118 can sometimes allow more efficient algorithms to be employed.
119 <a name="index-out_002dof_002dplace-177"></a>
120 <li><a name="index-FFTW_005fPRESERVE_005fINPUT-178"></a><code>FFTW_PRESERVE_INPUT</code> specifies that an out-of-place transform must
121 <em>not change its input</em> array. This is ordinarily the
122 <em>default</em>, except for c2r and hc2r (i.e. complex-to-real)
123 transforms for which <code>FFTW_DESTROY_INPUT</code> is the default. In the
124 latter cases, passing <code>FFTW_PRESERVE_INPUT</code> will attempt to use
125 algorithms that do not destroy the input, at the expense of worse
126 performance; for multi-dimensional c2r transforms, however, no
127 input-preserving algorithms are implemented and the planner will return
128 <code>NULL</code> if one is requested.
129 <a name="index-c2r-179"></a><a name="index-hc2r-180"></a>
130 <li><a name="index-FFTW_005fUNALIGNED-181"></a><a name="index-alignment-182"></a><code>FFTW_UNALIGNED</code> specifies that the algorithm may not impose any
131 unusual alignment requirements on the input/output arrays (i.e. no
132 SIMD may be used). This flag is normally <em>not necessary</em>, since
133 the planner automatically detects misaligned arrays. The only use for
134 this flag is if you want to use the new-array execute interface to
135 execute a given plan on a different array that may not be aligned like
136 the original. (Using <code>fftw_malloc</code> makes this flag unnecessary
137 even then.)
138
139 </ul>
140
141 <h5 class="subsubheading">Limiting planning time</h5>
142
143 <pre class="example"> extern void fftw_set_timelimit(double seconds);
144 </pre>
145 <p><a name="index-fftw_005fset_005ftimelimit-183"></a>
146 This function instructs FFTW to spend at most <code>seconds</code> seconds
147 (approximately) in the planner. If <code>seconds ==
148 FFTW_NO_TIMELIMIT</code> (the default value, which is negative), then
149 planning time is unbounded. Otherwise, FFTW plans with a
150 progressively wider range of algorithms until the the given time limit
151 is reached or the given range of algorithms is explored, returning the
152 best available plan.
153 <a name="index-FFTW_005fNO_005fTIMELIMIT-184"></a>
154
155 <p>For example, specifying <code>FFTW_PATIENT</code> first plans in
156 <code>FFTW_ESTIMATE</code> mode, then in <code>FFTW_MEASURE</code> mode, then
157 finally (time permitting) in <code>FFTW_PATIENT</code>. If
158 <code>FFTW_EXHAUSTIVE</code> is specified instead, the planner will further
159 progress to <code>FFTW_EXHAUSTIVE</code> mode.
160
161 <p>Note that the <code>seconds</code> argument specifies only a rough limit; in
162 practice, the planner may use somewhat more time if the time limit is
163 reached when the planner is in the middle of an operation that cannot
164 be interrupted. At the very least, the planner will complete planning
165 in <code>FFTW_ESTIMATE</code> mode (which is thus equivalent to a time limit
166 of 0).
167
168 <!-- =========> -->
169 </body></html>
170