Mercurial > hg > sv-dependency-builds

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