Mercurial > hg > sv-dependency-builds

annotate src/fftw-3.3.3/doc/html/Upgrading-from-FFTW-version-2.html @ 95:89f5e221ed7b

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