Mercurial > hg > sv-dependency-builds

comparison src/fftw-3.3.8/doc/html/Planner-Flags.html @ 167:bd3cc4d1df30

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add FFTW 3.3.8 source, and a Linux build
author Chris Cannam <cannam@all-day-breakfast.com>
date Tue, 19 Nov 2019 14:52:55 +0000
parents
children
comparison
equal deleted inserted replaced
166:cbd6d7e562c7 167:bd3cc4d1df30
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html>
3 <!-- This manual is for FFTW
4 (version 3.3.8, 24 May 2018).
5
6 Copyright (C) 2003 Matteo Frigo.
7
8 Copyright (C) 2003 Massachusetts Institute of Technology.
9
10 Permission is granted to make and distribute verbatim copies of this
11 manual provided the copyright notice and this permission notice are
12 preserved on all copies.
13
14 Permission is granted to copy and distribute modified versions of this
15 manual under the conditions for verbatim copying, provided that the
16 entire resulting derived work is distributed under the terms of a
17 permission notice identical to this one.
18
19 Permission is granted to copy and distribute translations of this manual
20 into another language, under the above conditions for modified versions,
21 except that this permission notice may be stated in a translation
22 approved by the Free Software Foundation. -->
23 <!-- Created by GNU Texinfo 6.3, http://www.gnu.org/software/texinfo/ -->
24 <head>
25 <title>FFTW 3.3.8: Planner Flags</title>
26
27 <meta name="description" content="FFTW 3.3.8: Planner Flags">
28 <meta name="keywords" content="FFTW 3.3.8: Planner Flags">
29 <meta name="resource-type" content="document">
30 <meta name="distribution" content="global">
31 <meta name="Generator" content="makeinfo">
32 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
33 <link href="index.html#Top" rel="start" title="Top">
34 <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
35 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
36 <link href="Basic-Interface.html#Basic-Interface" rel="up" title="Basic Interface">
37 <link href="Real_002ddata-DFTs.html#Real_002ddata-DFTs" rel="next" title="Real-data DFTs">
38 <link href="Complex-DFTs.html#Complex-DFTs" rel="prev" title="Complex DFTs">
39 <style type="text/css">
40 <!--
41 a.summary-letter {text-decoration: none}
42 blockquote.indentedblock {margin-right: 0em}
43 blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
44 blockquote.smallquotation {font-size: smaller}
45 div.display {margin-left: 3.2em}
46 div.example {margin-left: 3.2em}
47 div.lisp {margin-left: 3.2em}
48 div.smalldisplay {margin-left: 3.2em}
49 div.smallexample {margin-left: 3.2em}
50 div.smalllisp {margin-left: 3.2em}
51 kbd {font-style: oblique}
52 pre.display {font-family: inherit}
53 pre.format {font-family: inherit}
54 pre.menu-comment {font-family: serif}
55 pre.menu-preformatted {font-family: serif}
56 pre.smalldisplay {font-family: inherit; font-size: smaller}
57 pre.smallexample {font-size: smaller}
58 pre.smallformat {font-family: inherit; font-size: smaller}
59 pre.smalllisp {font-size: smaller}
60 span.nolinebreak {white-space: nowrap}
61 span.roman {font-family: initial; font-weight: normal}
62 span.sansserif {font-family: sans-serif; font-weight: normal}
63 ul.no-bullet {list-style: none}
64 -->
65 </style>
66
67
68 </head>
69
70 <body lang="en">
71 <a name="Planner-Flags"></a>
72 <div class="header">
73 <p>
74 Next: <a href="Real_002ddata-DFTs.html#Real_002ddata-DFTs" accesskey="n" rel="next">Real-data DFTs</a>, Previous: <a href="Complex-DFTs.html#Complex-DFTs" accesskey="p" rel="prev">Complex DFTs</a>, Up: <a href="Basic-Interface.html#Basic-Interface" accesskey="u" rel="up">Basic Interface</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
75 </div>
76 <hr>
77 <a name="Planner-Flags-1"></a>
78 <h4 class="subsection">4.3.2 Planner Flags</h4>
79
80 <p>All of the planner routines in FFTW accept an integer <code>flags</code>
81 argument, which is a bitwise OR (&lsquo;<samp>|</samp>&rsquo;) of zero or more of the flag
82 constants defined below. These flags control the rigor (and time) of
83 the planning process, and can also impose (or lift) restrictions on the
84 type of transform algorithm that is employed.
85 </p>
86 <p><em>Important:</em> the planner overwrites the input array during
87 planning unless a saved plan (see <a href="Wisdom.html#Wisdom">Wisdom</a>) is available for that
88 problem, so you should initialize your input data after creating the
89 plan. The only exceptions to this are the <code>FFTW_ESTIMATE</code> and
90 <code>FFTW_WISDOM_ONLY</code> flags, as mentioned below.
91 </p>
92 <p>In all cases, if wisdom is available for the given problem that was
93 created with equal-or-greater planning rigor, then the more rigorous
94 wisdom is used. For example, in <code>FFTW_ESTIMATE</code> mode any available
95 wisdom is used, whereas in <code>FFTW_PATIENT</code> mode only wisdom created
96 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>.
97 </p>
98 <a name="Planning_002drigor-flags"></a>
99 <h4 class="subsubheading">Planning-rigor flags</h4>
100 <ul>
101 <li> <a name="index-FFTW_005fESTIMATE-2"></a>
102 <code>FFTW_ESTIMATE</code> specifies that, instead of actual measurements of
103 different algorithms, a simple heuristic is used to pick a (probably
104 sub-optimal) plan quickly. With this flag, the input/output arrays are
105 not overwritten during planning.
106
107 </li><li> <a name="index-FFTW_005fMEASURE-2"></a>
108 <code>FFTW_MEASURE</code> tells FFTW to find an optimized plan by actually
109 <em>computing</em> several FFTs and measuring their execution time.
110 Depending on your machine, this can take some time (often a few
111 seconds). <code>FFTW_MEASURE</code> is the default planning option.
112
113 </li><li> <a name="index-FFTW_005fPATIENT-2"></a>
114 <code>FFTW_PATIENT</code> is like <code>FFTW_MEASURE</code>, but considers a wider
115 range of algorithms and often produces a &ldquo;more optimal&rdquo; plan
116 (especially for large transforms), but at the expense of several times
117 longer planning time (especially for large transforms).
118
119 </li><li> <a name="index-FFTW_005fEXHAUSTIVE-1"></a>
120 <code>FFTW_EXHAUSTIVE</code> is like <code>FFTW_PATIENT</code>, but considers an
121 even wider range of algorithms, including many that we think are
122 unlikely to be fast, to produce the most optimal plan but with a
123 substantially increased planning time.
124
125 </li><li> <a name="index-FFTW_005fWISDOM_005fONLY"></a>
126 <code>FFTW_WISDOM_ONLY</code> is a special planning mode in which the plan
127 is only created if wisdom is available for the given problem, and
128 otherwise a <code>NULL</code> plan is returned. This can be combined with
129 other flags, e.g. &lsquo;<samp>FFTW_WISDOM_ONLY | FFTW_PATIENT</samp>&rsquo; creates a
130 plan only if wisdom is available that was created in
131 <code>FFTW_PATIENT</code> or <code>FFTW_EXHAUSTIVE</code> mode. The
132 <code>FFTW_WISDOM_ONLY</code> flag is intended for users who need to detect
133 whether wisdom is available; for example, if wisdom is not available
134 one may wish to allocate new arrays for planning so that user data is
135 not overwritten.
136
137 </li></ul>
138
139 <a name="Algorithm_002drestriction-flags"></a>
140 <h4 class="subsubheading">Algorithm-restriction flags</h4>
141 <ul>
142 <li> <a name="index-FFTW_005fDESTROY_005fINPUT"></a>
143 <code>FFTW_DESTROY_INPUT</code> specifies that an out-of-place transform is
144 allowed to <em>overwrite its input</em> array with arbitrary data; this
145 can sometimes allow more efficient algorithms to be employed.
146 <a name="index-out_002dof_002dplace"></a>
147
148 </li><li> <a name="index-FFTW_005fPRESERVE_005fINPUT-1"></a>
149 <code>FFTW_PRESERVE_INPUT</code> specifies that an out-of-place transform must
150 <em>not change its input</em> array. This is ordinarily the
151 <em>default</em>, except for c2r and hc2r (i.e. complex-to-real)
152 transforms for which <code>FFTW_DESTROY_INPUT</code> is the default. In the
153 latter cases, passing <code>FFTW_PRESERVE_INPUT</code> will attempt to use
154 algorithms that do not destroy the input, at the expense of worse
155 performance; for multi-dimensional c2r transforms, however, no
156 input-preserving algorithms are implemented and the planner will return
157 <code>NULL</code> if one is requested.
158 <a name="index-c2r-1"></a>
159 <a name="index-hc2r-1"></a>
160
161 </li><li> <a name="index-FFTW_005fUNALIGNED"></a>
162 <a name="index-alignment-1"></a>
163 <a name="index-fftw_005fmalloc-4"></a>
164 <a name="index-fftw_005falignment_005fof"></a>
165 <code>FFTW_UNALIGNED</code> specifies that the algorithm may not impose any
166 unusual alignment requirements on the input/output arrays (i.e. no
167 SIMD may be used). This flag is normally <em>not necessary</em>, since
168 the planner automatically detects misaligned arrays. The only use for
169 this flag is if you want to use the new-array execute interface to
170 execute a given plan on a different array that may not be aligned like
171 the original. (Using <code>fftw_malloc</code> makes this flag unnecessary
172 even then. You can also use <code>fftw_alignment_of</code> to detect
173 whether two arrays are equivalently aligned.)
174
175 </li></ul>
176
177 <a name="Limiting-planning-time"></a>
178 <h4 class="subsubheading">Limiting planning time</h4>
179
180 <div class="example">
181 <pre class="example">extern void fftw_set_timelimit(double seconds);
182 </pre></div>
183 <a name="index-fftw_005fset_005ftimelimit"></a>
184
185 <p>This function instructs FFTW to spend at most <code>seconds</code> seconds
186 (approximately) in the planner. If <code>seconds ==
187 FFTW_NO_TIMELIMIT</code> (the default value, which is negative), then
188 planning time is unbounded. Otherwise, FFTW plans with a
189 progressively wider range of algorithms until the the given time limit
190 is reached or the given range of algorithms is explored, returning the
191 best available plan.
192 <a name="index-FFTW_005fNO_005fTIMELIMIT"></a>
193 </p>
194
195 <p>For example, specifying <code>FFTW_PATIENT</code> first plans in
196 <code>FFTW_ESTIMATE</code> mode, then in <code>FFTW_MEASURE</code> mode, then
197 finally (time permitting) in <code>FFTW_PATIENT</code>. If
198 <code>FFTW_EXHAUSTIVE</code> is specified instead, the planner will further
199 progress to <code>FFTW_EXHAUSTIVE</code> mode.
200 </p>
201 <p>Note that the <code>seconds</code> argument specifies only a rough limit; in
202 practice, the planner may use somewhat more time if the time limit is
203 reached when the planner is in the middle of an operation that cannot
204 be interrupted. At the very least, the planner will complete planning
205 in <code>FFTW_ESTIMATE</code> mode (which is thus equivalent to a time limit
206 of 0).
207 </p>
208
209 <hr>
210 <div class="header">
211 <p>
212 Next: <a href="Real_002ddata-DFTs.html#Real_002ddata-DFTs" accesskey="n" rel="next">Real-data DFTs</a>, Previous: <a href="Complex-DFTs.html#Complex-DFTs" accesskey="p" rel="prev">Complex DFTs</a>, Up: <a href="Basic-Interface.html#Basic-Interface" accesskey="u" rel="up">Basic Interface</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
213 </div>
214
215
216
217 </body>
218 </html>