Mercurial > hg > sv-dependency-builds

annotate src/fftw-3.3.5/doc/html/Planner-Flags.html @ 83:ae30d91d2ffe

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