Mercurial > hg > sv-dependency-builds

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