Mercurial > hg > sv-dependency-builds

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