Mercurial > hg > sv-dependency-builds

comparison src/fftw-3.3.5/doc/html/Upgrading-from-FFTW-version-2.html @ 127:7867fa7e1b6b

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