Mercurial > hg > sv-dependency-builds

annotate src/fftw-3.3.5/doc/html/Upgrading-from-FFTW-version-2.html @ 169:223a55898ab9 tip default

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add null config files
author Chris Cannam <cannam@all-day-breakfast.com>
date Mon, 02 Mar 2020 14:03:47 +0000
parents 7867fa7e1b6b
children
rev   line source
cannam@127 1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
cannam@127 2 <html>
cannam@127 3 <!-- This manual is for FFTW
cannam@127 4 (version 3.3.5, 30 July 2016).
cannam@127 5
cannam@127 6 Copyright (C) 2003 Matteo Frigo.
cannam@127 7
cannam@127 8 Copyright (C) 2003 Massachusetts Institute of Technology.
cannam@127 9
cannam@127 10 Permission is granted to make and distribute verbatim copies of this
cannam@127 11 manual provided the copyright notice and this permission notice are
cannam@127 12 preserved on all copies.
cannam@127 13
cannam@127 14 Permission is granted to copy and distribute modified versions of this
cannam@127 15 manual under the conditions for verbatim copying, provided that the
cannam@127 16 entire resulting derived work is distributed under the terms of a
cannam@127 17 permission notice identical to this one.
cannam@127 18
cannam@127 19 Permission is granted to copy and distribute translations of this manual
cannam@127 20 into another language, under the above conditions for modified versions,
cannam@127 21 except that this permission notice may be stated in a translation
cannam@127 22 approved by the Free Software Foundation. -->
cannam@127 23 <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
cannam@127 24 <head>
cannam@127 25 <title>FFTW 3.3.5: Upgrading from FFTW version 2</title>
cannam@127 26
cannam@127 27 <meta name="description" content="FFTW 3.3.5: Upgrading from FFTW version 2">
cannam@127 28 <meta name="keywords" content="FFTW 3.3.5: Upgrading from FFTW version 2">
cannam@127 29 <meta name="resource-type" content="document">
cannam@127 30 <meta name="distribution" content="global">
cannam@127 31 <meta name="Generator" content="makeinfo">
cannam@127 32 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
cannam@127 33 <link href="index.html#Top" rel="start" title="Top">
cannam@127 34 <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
cannam@127 35 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
cannam@127 36 <link href="index.html#Top" rel="up" title="Top">
cannam@127 37 <link href="Installation-and-Customization.html#Installation-and-Customization" rel="next" title="Installation and Customization">
cannam@127 38 <link href="Wisdom-of-Fortran_003f.html#Wisdom-of-Fortran_003f" rel="prev" title="Wisdom of Fortran?">
cannam@127 39 <style type="text/css">
cannam@127 40 <!--
cannam@127 41 a.summary-letter {text-decoration: none}
cannam@127 42 blockquote.smallquotation {font-size: smaller}
cannam@127 43 div.display {margin-left: 3.2em}
cannam@127 44 div.example {margin-left: 3.2em}
cannam@127 45 div.indentedblock {margin-left: 3.2em}
cannam@127 46 div.lisp {margin-left: 3.2em}
cannam@127 47 div.smalldisplay {margin-left: 3.2em}
cannam@127 48 div.smallexample {margin-left: 3.2em}
cannam@127 49 div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
cannam@127 50 div.smalllisp {margin-left: 3.2em}
cannam@127 51 kbd {font-style:oblique}
cannam@127 52 pre.display {font-family: inherit}
cannam@127 53 pre.format {font-family: inherit}
cannam@127 54 pre.menu-comment {font-family: serif}
cannam@127 55 pre.menu-preformatted {font-family: serif}
cannam@127 56 pre.smalldisplay {font-family: inherit; font-size: smaller}
cannam@127 57 pre.smallexample {font-size: smaller}
cannam@127 58 pre.smallformat {font-family: inherit; font-size: smaller}
cannam@127 59 pre.smalllisp {font-size: smaller}
cannam@127 60 span.nocodebreak {white-space:nowrap}
cannam@127 61 span.nolinebreak {white-space:nowrap}
cannam@127 62 span.roman {font-family:serif; font-weight:normal}
cannam@127 63 span.sansserif {font-family:sans-serif; font-weight:normal}
cannam@127 64 ul.no-bullet {list-style: none}
cannam@127 65 -->
cannam@127 66 </style>
cannam@127 67
cannam@127 68
cannam@127 69 </head>
cannam@127 70
cannam@127 71 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
cannam@127 72 <a name="Upgrading-from-FFTW-version-2"></a>
cannam@127 73 <div class="header">
cannam@127 74 <p>
cannam@127 75 Next: <a href="Installation-and-Customization.html#Installation-and-Customization" accesskey="n" rel="next">Installation and Customization</a>, Previous: <a href="Calling-FFTW-from-Legacy-Fortran.html#Calling-FFTW-from-Legacy-Fortran" accesskey="p" rel="prev">Calling FFTW from Legacy Fortran</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</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>
cannam@127 76 </div>
cannam@127 77 <hr>
cannam@127 78 <a name="Upgrading-from-FFTW-version-2-1"></a>
cannam@127 79 <h2 class="chapter">9 Upgrading from FFTW version 2</h2>
cannam@127 80
cannam@127 81 <p>In this chapter, we outline the process for updating codes designed for
cannam@127 82 the older FFTW 2 interface to work with FFTW 3. The interface for FFTW
cannam@127 83 3 is not backwards-compatible with the interface for FFTW 2 and earlier
cannam@127 84 versions; codes written to use those versions will fail to link with
cannam@127 85 FFTW 3. Nor is it possible to write &ldquo;compatibility wrappers&rdquo; to
cannam@127 86 bridge the gap (at least not efficiently), because FFTW 3 has different
cannam@127 87 semantics from previous versions. However, upgrading should be a
cannam@127 88 straightforward process because the data formats are identical and the
cannam@127 89 overall style of planning/execution is essentially the same.
cannam@127 90 </p>
cannam@127 91 <p>Unlike FFTW 2, there are no separate header files for real and complex
cannam@127 92 transforms (or even for different precisions) in FFTW 3; all interfaces
cannam@127 93 are defined in the <code>&lt;fftw3.h&gt;</code> header file.
cannam@127 94 </p>
cannam@127 95 <a name="Numeric-Types"></a>
cannam@127 96 <h3 class="heading">Numeric Types</h3>
cannam@127 97
cannam@127 98 <p>The main difference in data types is that <code>fftw_complex</code> in FFTW 2
cannam@127 99 was defined as a <code>struct</code> with macros <code>c_re</code> and <code>c_im</code>
cannam@127 100 for accessing the real/imaginary parts. (This is binary-compatible with
cannam@127 101 FFTW 3 on any machine except perhaps for some older Crays in single
cannam@127 102 precision.) The equivalent macros for FFTW 3 are:
cannam@127 103 </p>
cannam@127 104 <div class="example">
cannam@127 105 <pre class="example">#define c_re(c) ((c)[0])
cannam@127 106 #define c_im(c) ((c)[1])
cannam@127 107 </pre></div>
cannam@127 108
cannam@127 109 <p>This does not work if you are using the C99 complex type, however,
cannam@127 110 unless you insert a <code>double*</code> typecast into the above macros
cannam@127 111 (see <a href="Complex-numbers.html#Complex-numbers">Complex numbers</a>).
cannam@127 112 </p>
cannam@127 113 <p>Also, FFTW 2 had an <code>fftw_real</code> typedef that was an alias for
cannam@127 114 <code>double</code> (in double precision). In FFTW 3 you should just use
cannam@127 115 <code>double</code> (or whatever precision you are employing).
cannam@127 116 </p>
cannam@127 117 <a name="Plans"></a>
cannam@127 118 <h3 class="heading">Plans</h3>
cannam@127 119
cannam@127 120 <p>The major difference between FFTW 2 and FFTW 3 is in the
cannam@127 121 planning/execution division of labor. In FFTW 2, plans were found for a
cannam@127 122 given transform size and type, and then could be applied to <em>any</em>
cannam@127 123 arrays and for <em>any</em> multiplicity/stride parameters. In FFTW 3,
cannam@127 124 you specify the particular arrays, stride parameters, etcetera when
cannam@127 125 creating the plan, and the plan is then executed for <em>those</em> arrays
cannam@127 126 (unless the guru interface is used) and <em>those</em> parameters
cannam@127 127 <em>only</em>. (FFTW 2 had &ldquo;specific planner&rdquo; routines that planned for
cannam@127 128 a particular array and stride, but the plan could still be used for
cannam@127 129 other arrays and strides.) That is, much of the information that was
cannam@127 130 formerly specified at execution time is now specified at planning time.
cannam@127 131 </p>
cannam@127 132 <p>Like FFTW 2&rsquo;s specific planner routines, the FFTW 3 planner overwrites
cannam@127 133 the input/output arrays unless you use <code>FFTW_ESTIMATE</code>.
cannam@127 134 </p>
cannam@127 135 <p>FFTW 2 had separate data types <code>fftw_plan</code>, <code>fftwnd_plan</code>,
cannam@127 136 <code>rfftw_plan</code>, and <code>rfftwnd_plan</code> for complex and real one- and
cannam@127 137 multi-dimensional transforms, and each type had its own &lsquo;<samp>destroy</samp>&rsquo;
cannam@127 138 function. In FFTW 3, all plans are of type <code>fftw_plan</code> and all are
cannam@127 139 destroyed by <code>fftw_destroy_plan(plan)</code>.
cannam@127 140 </p>
cannam@127 141 <p>Where you formerly used <code>fftw_create_plan</code> and <code>fftw_one</code> to
cannam@127 142 plan and compute a single 1d transform, you would now use
cannam@127 143 <code>fftw_plan_dft_1d</code> to plan the transform. If you used the generic
cannam@127 144 <code>fftw</code> function to execute the transform with multiplicity
cannam@127 145 (<code>howmany</code>) and stride parameters, you would now use the advanced
cannam@127 146 interface <code>fftw_plan_many_dft</code> to specify those parameters. The
cannam@127 147 plans are now executed with <code>fftw_execute(plan)</code>, which takes all
cannam@127 148 of its parameters (including the input/output arrays) from the plan.
cannam@127 149 </p>
cannam@127 150 <p>In-place transforms no longer interpret their output argument as scratch
cannam@127 151 space, nor is there an <code>FFTW_IN_PLACE</code> flag. You simply pass the
cannam@127 152 same pointer for both the input and output arguments. (Previously, the
cannam@127 153 output <code>ostride</code> and <code>odist</code> parameters were ignored for
cannam@127 154 in-place transforms; now, if they are specified via the advanced
cannam@127 155 interface, they are significant even in the in-place case, although they
cannam@127 156 should normally equal the corresponding input parameters.)
cannam@127 157 </p>
cannam@127 158 <p>The <code>FFTW_ESTIMATE</code> and <code>FFTW_MEASURE</code> flags have the same
cannam@127 159 meaning as before, although the planning time will differ. You may also
cannam@127 160 consider using <code>FFTW_PATIENT</code>, which is like <code>FFTW_MEASURE</code>
cannam@127 161 except that it takes more time in order to consider a wider variety of
cannam@127 162 algorithms.
cannam@127 163 </p>
cannam@127 164 <p>For multi-dimensional complex DFTs, instead of <code>fftwnd_create_plan</code>
cannam@127 165 (or <code>fftw2d_create_plan</code> or <code>fftw3d_create_plan</code>), followed by
cannam@127 166 <code>fftwnd_one</code>, you would use <code>fftw_plan_dft</code> (or
cannam@127 167 <code>fftw_plan_dft_2d</code> or <code>fftw_plan_dft_3d</code>). followed by
cannam@127 168 <code>fftw_execute</code>. If you used <code>fftwnd</code> to to specify strides
cannam@127 169 etcetera, you would instead specify these via <code>fftw_plan_many_dft</code>.
cannam@127 170 </p>
cannam@127 171 <p>The analogues to <code>rfftw_create_plan</code> and <code>rfftw_one</code> with
cannam@127 172 <code>FFTW_REAL_TO_COMPLEX</code> or <code>FFTW_COMPLEX_TO_REAL</code> directions
cannam@127 173 are <code>fftw_plan_r2r_1d</code> with kind <code>FFTW_R2HC</code> or
cannam@127 174 <code>FFTW_HC2R</code>, followed by <code>fftw_execute</code>. The stride etcetera
cannam@127 175 arguments of <code>rfftw</code> are now in <code>fftw_plan_many_r2r</code>.
cannam@127 176 </p>
cannam@127 177 <p>Instead of <code>rfftwnd_create_plan</code> (or <code>rfftw2d_create_plan</code> or
cannam@127 178 <code>rfftw3d_create_plan</code>) followed by
cannam@127 179 <code>rfftwnd_one_real_to_complex</code> or
cannam@127 180 <code>rfftwnd_one_complex_to_real</code>, you now use <code>fftw_plan_dft_r2c</code>
cannam@127 181 (or <code>fftw_plan_dft_r2c_2d</code> or <code>fftw_plan_dft_r2c_3d</code>) or
cannam@127 182 <code>fftw_plan_dft_c2r</code> (or <code>fftw_plan_dft_c2r_2d</code> or
cannam@127 183 <code>fftw_plan_dft_c2r_3d</code>), respectively, followed by
cannam@127 184 <code>fftw_execute</code>. As usual, the strides etcetera of
cannam@127 185 <code>rfftwnd_real_to_complex</code> or <code>rfftwnd_complex_to_real</code> are no
cannam@127 186 specified in the advanced planner routines,
cannam@127 187 <code>fftw_plan_many_dft_r2c</code> or <code>fftw_plan_many_dft_c2r</code>.
cannam@127 188 </p>
cannam@127 189 <a name="Wisdom-2"></a>
cannam@127 190 <h3 class="heading">Wisdom</h3>
cannam@127 191
cannam@127 192 <p>In FFTW 2, you had to supply the <code>FFTW_USE_WISDOM</code> flag in order to
cannam@127 193 use wisdom; in FFTW 3, wisdom is always used. (You could simulate the
cannam@127 194 FFTW 2 wisdom-less behavior by calling <code>fftw_forget_wisdom</code> after
cannam@127 195 every planner call.)
cannam@127 196 </p>
cannam@127 197 <p>The FFTW 3 wisdom import/export routines are almost the same as before
cannam@127 198 (although the storage format is entirely different). There is one
cannam@127 199 significant difference, however. In FFTW 2, the import routines would
cannam@127 200 never read past the end of the wisdom, so you could store extra data
cannam@127 201 beyond the wisdom in the same file, for example. In FFTW 3, the
cannam@127 202 file-import routine may read up to a few hundred bytes past the end of
cannam@127 203 the wisdom, so you cannot store other data just beyond it.<a name="DOCF11" href="#FOOT11"><sup>11</sup></a>
cannam@127 204 </p>
cannam@127 205 <p>Wisdom has been enhanced by additional humility in FFTW 3: whereas FFTW
cannam@127 206 2 would re-use wisdom for a given transform size regardless of the
cannam@127 207 stride etc., in FFTW 3 wisdom is only used with the strides etc. for
cannam@127 208 which it was created. Unfortunately, this means FFTW 3 has to create
cannam@127 209 new plans from scratch more often than FFTW 2 (in FFTW 2, planning
cannam@127 210 e.g. one transform of size 1024 also created wisdom for all smaller
cannam@127 211 powers of 2, but this no longer occurs).
cannam@127 212 </p>
cannam@127 213 <p>FFTW 3 also has the new routine <code>fftw_import_system_wisdom</code> to
cannam@127 214 import wisdom from a standard system-wide location.
cannam@127 215 </p>
cannam@127 216 <a name="Memory-allocation"></a>
cannam@127 217 <h3 class="heading">Memory allocation</h3>
cannam@127 218
cannam@127 219 <p>In FFTW 3, we recommend allocating your arrays with <code>fftw_malloc</code>
cannam@127 220 and deallocating them with <code>fftw_free</code>; this is not required, but
cannam@127 221 allows optimal performance when SIMD acceleration is used. (Those two
cannam@127 222 functions actually existed in FFTW 2, and worked the same way, but were
cannam@127 223 not documented.)
cannam@127 224 </p>
cannam@127 225 <p>In FFTW 2, there were <code>fftw_malloc_hook</code> and <code>fftw_free_hook</code>
cannam@127 226 functions that allowed the user to replace FFTW&rsquo;s memory-allocation
cannam@127 227 routines (e.g. to implement different error-handling, since by default
cannam@127 228 FFTW prints an error message and calls <code>exit</code> to abort the program
cannam@127 229 if <code>malloc</code> returns <code>NULL</code>). These hooks are not supported in
cannam@127 230 FFTW 3; those few users who require this functionality can just
cannam@127 231 directly modify the memory-allocation routines in FFTW (they are defined
cannam@127 232 in <code>kernel/alloc.c</code>).
cannam@127 233 </p>
cannam@127 234 <a name="Fortran-interface"></a>
cannam@127 235 <h3 class="heading">Fortran interface</h3>
cannam@127 236
cannam@127 237 <p>In FFTW 2, the subroutine names were obtained by replacing &lsquo;<samp>fftw_</samp>&rsquo;
cannam@127 238 with &lsquo;<samp>fftw_f77</samp>&rsquo;; in FFTW 3, you replace &lsquo;<samp>fftw_</samp>&rsquo; with
cannam@127 239 &lsquo;<samp>dfftw_</samp>&rsquo; (or &lsquo;<samp>sfftw_</samp>&rsquo; or &lsquo;<samp>lfftw_</samp>&rsquo;, depending upon the
cannam@127 240 precision).
cannam@127 241 </p>
cannam@127 242 <p>In FFTW 3, we have begun recommending that you always declare the type
cannam@127 243 used to store plans as <code>integer*8</code>. (Too many people didn&rsquo;t notice
cannam@127 244 our instruction to switch from <code>integer</code> to <code>integer*8</code> for
cannam@127 245 64-bit machines.)
cannam@127 246 </p>
cannam@127 247 <p>In FFTW 3, we provide a <code>fftw3.f</code> &ldquo;header file&rdquo; to include in
cannam@127 248 your code (and which is officially installed on Unix systems). (In FFTW
cannam@127 249 2, we supplied a <code>fftw_f77.i</code> file, but it was not installed.)
cannam@127 250 </p>
cannam@127 251 <p>Otherwise, the C-Fortran interface relationship is much the same as it
cannam@127 252 was before (e.g. return values become initial parameters, and
cannam@127 253 multi-dimensional arrays are in column-major order). Unlike FFTW 2, we
cannam@127 254 do provide some support for wisdom import/export in Fortran
cannam@127 255 (see <a href="Wisdom-of-Fortran_003f.html#Wisdom-of-Fortran_003f">Wisdom of Fortran?</a>).
cannam@127 256 </p>
cannam@127 257 <a name="Threads"></a>
cannam@127 258 <h3 class="heading">Threads</h3>
cannam@127 259
cannam@127 260 <p>Like FFTW 2, only the execution routines are thread-safe. All planner
cannam@127 261 routines, etcetera, should be called by only a single thread at a time
cannam@127 262 (see <a href="Thread-safety.html#Thread-safety">Thread safety</a>). <em>Unlike</em> FFTW 2, there is no special
cannam@127 263 <code>FFTW_THREADSAFE</code> flag for the planner to allow a given plan to be
cannam@127 264 usable by multiple threads in parallel; this is now the case by default.
cannam@127 265 </p>
cannam@127 266 <p>The multi-threaded version of FFTW 2 required you to pass the number of
cannam@127 267 threads each time you execute the transform. The number of threads is
cannam@127 268 now stored in the plan, and is specified before the planner is called by
cannam@127 269 <code>fftw_plan_with_nthreads</code>. The threads initialization routine used
cannam@127 270 to be called <code>fftw_threads_init</code> and would return zero on success;
cannam@127 271 the new routine is called <code>fftw_init_threads</code> and returns zero on
cannam@127 272 failure. See <a href="Multi_002dthreaded-FFTW.html#Multi_002dthreaded-FFTW">Multi-threaded FFTW</a>.
cannam@127 273 </p>
cannam@127 274 <p>There is no separate threads header file in FFTW 3; all the function
cannam@127 275 prototypes are in <code>&lt;fftw3.h&gt;</code>. However, you still have to link to
cannam@127 276 a separate library (<code>-lfftw3_threads -lfftw3 -lm</code> on Unix), as well as
cannam@127 277 to the threading library (e.g. POSIX threads on Unix).
cannam@127 278 </p>
cannam@127 279 <div class="footnote">
cannam@127 280 <hr>
cannam@127 281 <h4 class="footnotes-heading">Footnotes</h4>
cannam@127 282
cannam@127 283 <h3><a name="FOOT11" href="#DOCF11">(11)</a></h3>
cannam@127 284 <p>We
cannam@127 285 do our own buffering because GNU libc I/O routines are horribly slow for
cannam@127 286 single-character I/O, apparently for thread-safety reasons (whether you
cannam@127 287 are using threads or not).</p>
cannam@127 288 </div>
cannam@127 289 <hr>
cannam@127 290 <div class="header">
cannam@127 291 <p>
cannam@127 292 Next: <a href="Installation-and-Customization.html#Installation-and-Customization" accesskey="n" rel="next">Installation and Customization</a>, Previous: <a href="Calling-FFTW-from-Legacy-Fortran.html#Calling-FFTW-from-Legacy-Fortran" accesskey="p" rel="prev">Calling FFTW from Legacy Fortran</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</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>
cannam@127 293 </div>
cannam@127 294
cannam@127 295
cannam@127 296
cannam@127 297 </body>
cannam@127 298 </html>