Mercurial > hg > sv-dependency-builds

comparison src/fftw-3.3.8/doc/html/Upgrading-from-FFTW-version-2.html @ 82:d0c2a83c1364

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