Chris@19: Chris@19: Chris@19: Upgrading from FFTW version 2 - FFTW 3.3.4 Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19: Chris@19:
Chris@19: Chris@19:

Chris@19: Next: , Chris@19: Previous: Calling FFTW from Legacy Fortran, Chris@19: Up: Top Chris@19:


Chris@19:
Chris@19: Chris@19:

9 Upgrading from FFTW version 2

Chris@19: Chris@19:

In this chapter, we outline the process for updating codes designed for Chris@19: the older FFTW 2 interface to work with FFTW 3. The interface for FFTW Chris@19: 3 is not backwards-compatible with the interface for FFTW 2 and earlier Chris@19: versions; codes written to use those versions will fail to link with Chris@19: FFTW 3. Nor is it possible to write “compatibility wrappers” to Chris@19: bridge the gap (at least not efficiently), because FFTW 3 has different Chris@19: semantics from previous versions. However, upgrading should be a Chris@19: straightforward process because the data formats are identical and the Chris@19: overall style of planning/execution is essentially the same. Chris@19: Chris@19:

Unlike FFTW 2, there are no separate header files for real and complex Chris@19: transforms (or even for different precisions) in FFTW 3; all interfaces Chris@19: are defined in the <fftw3.h> header file. Chris@19: Chris@19:

Numeric Types

Chris@19: Chris@19:

The main difference in data types is that fftw_complex in FFTW 2 Chris@19: was defined as a struct with macros c_re and c_im Chris@19: for accessing the real/imaginary parts. (This is binary-compatible with Chris@19: FFTW 3 on any machine except perhaps for some older Crays in single Chris@19: precision.) The equivalent macros for FFTW 3 are: Chris@19: Chris@19:

     #define c_re(c) ((c)[0])
Chris@19:      #define c_im(c) ((c)[1])
Chris@19: 
Chris@19:

This does not work if you are using the C99 complex type, however, Chris@19: unless you insert a double* typecast into the above macros Chris@19: (see Complex numbers). Chris@19: Chris@19:

Also, FFTW 2 had an fftw_real typedef that was an alias for Chris@19: double (in double precision). In FFTW 3 you should just use Chris@19: double (or whatever precision you are employing). Chris@19: Chris@19:

Plans

Chris@19: Chris@19:

The major difference between FFTW 2 and FFTW 3 is in the Chris@19: planning/execution division of labor. In FFTW 2, plans were found for a Chris@19: given transform size and type, and then could be applied to any Chris@19: arrays and for any multiplicity/stride parameters. In FFTW 3, Chris@19: you specify the particular arrays, stride parameters, etcetera when Chris@19: creating the plan, and the plan is then executed for those arrays Chris@19: (unless the guru interface is used) and those parameters Chris@19: only. (FFTW 2 had “specific planner” routines that planned for Chris@19: a particular array and stride, but the plan could still be used for Chris@19: other arrays and strides.) That is, much of the information that was Chris@19: formerly specified at execution time is now specified at planning time. Chris@19: Chris@19:

Like FFTW 2's specific planner routines, the FFTW 3 planner overwrites Chris@19: the input/output arrays unless you use FFTW_ESTIMATE. Chris@19: Chris@19:

FFTW 2 had separate data types fftw_plan, fftwnd_plan, Chris@19: rfftw_plan, and rfftwnd_plan for complex and real one- and Chris@19: multi-dimensional transforms, and each type had its own ‘destroy’ Chris@19: function. In FFTW 3, all plans are of type fftw_plan and all are Chris@19: destroyed by fftw_destroy_plan(plan). Chris@19: Chris@19:

Where you formerly used fftw_create_plan and fftw_one to Chris@19: plan and compute a single 1d transform, you would now use Chris@19: fftw_plan_dft_1d to plan the transform. If you used the generic Chris@19: fftw function to execute the transform with multiplicity Chris@19: (howmany) and stride parameters, you would now use the advanced Chris@19: interface fftw_plan_many_dft to specify those parameters. The Chris@19: plans are now executed with fftw_execute(plan), which takes all Chris@19: of its parameters (including the input/output arrays) from the plan. Chris@19: Chris@19:

In-place transforms no longer interpret their output argument as scratch Chris@19: space, nor is there an FFTW_IN_PLACE flag. You simply pass the Chris@19: same pointer for both the input and output arguments. (Previously, the Chris@19: output ostride and odist parameters were ignored for Chris@19: in-place transforms; now, if they are specified via the advanced Chris@19: interface, they are significant even in the in-place case, although they Chris@19: should normally equal the corresponding input parameters.) Chris@19: Chris@19:

The FFTW_ESTIMATE and FFTW_MEASURE flags have the same Chris@19: meaning as before, although the planning time will differ. You may also Chris@19: consider using FFTW_PATIENT, which is like FFTW_MEASURE Chris@19: except that it takes more time in order to consider a wider variety of Chris@19: algorithms. Chris@19: Chris@19:

For multi-dimensional complex DFTs, instead of fftwnd_create_plan Chris@19: (or fftw2d_create_plan or fftw3d_create_plan), followed by Chris@19: fftwnd_one, you would use fftw_plan_dft (or Chris@19: fftw_plan_dft_2d or fftw_plan_dft_3d). followed by Chris@19: fftw_execute. If you used fftwnd to to specify strides Chris@19: etcetera, you would instead specify these via fftw_plan_many_dft. Chris@19: Chris@19:

The analogues to rfftw_create_plan and rfftw_one with Chris@19: FFTW_REAL_TO_COMPLEX or FFTW_COMPLEX_TO_REAL directions Chris@19: are fftw_plan_r2r_1d with kind FFTW_R2HC or Chris@19: FFTW_HC2R, followed by fftw_execute. The stride etcetera Chris@19: arguments of rfftw are now in fftw_plan_many_r2r. Chris@19: Chris@19:

Instead of rfftwnd_create_plan (or rfftw2d_create_plan or Chris@19: rfftw3d_create_plan) followed by Chris@19: rfftwnd_one_real_to_complex or Chris@19: rfftwnd_one_complex_to_real, you now use fftw_plan_dft_r2c Chris@19: (or fftw_plan_dft_r2c_2d or fftw_plan_dft_r2c_3d) or Chris@19: fftw_plan_dft_c2r (or fftw_plan_dft_c2r_2d or Chris@19: fftw_plan_dft_c2r_3d), respectively, followed by Chris@19: fftw_execute. As usual, the strides etcetera of Chris@19: rfftwnd_real_to_complex or rfftwnd_complex_to_real are no Chris@19: specified in the advanced planner routines, Chris@19: fftw_plan_many_dft_r2c or fftw_plan_many_dft_c2r. Chris@19: Chris@19:

Wisdom

Chris@19: Chris@19:

In FFTW 2, you had to supply the FFTW_USE_WISDOM flag in order to Chris@19: use wisdom; in FFTW 3, wisdom is always used. (You could simulate the Chris@19: FFTW 2 wisdom-less behavior by calling fftw_forget_wisdom after Chris@19: every planner call.) Chris@19: Chris@19:

The FFTW 3 wisdom import/export routines are almost the same as before Chris@19: (although the storage format is entirely different). There is one Chris@19: significant difference, however. In FFTW 2, the import routines would Chris@19: never read past the end of the wisdom, so you could store extra data Chris@19: beyond the wisdom in the same file, for example. In FFTW 3, the Chris@19: file-import routine may read up to a few hundred bytes past the end of Chris@19: the wisdom, so you cannot store other data just beyond it.1 Chris@19: Chris@19:

Wisdom has been enhanced by additional humility in FFTW 3: whereas FFTW Chris@19: 2 would re-use wisdom for a given transform size regardless of the Chris@19: stride etc., in FFTW 3 wisdom is only used with the strides etc. for Chris@19: which it was created. Unfortunately, this means FFTW 3 has to create Chris@19: new plans from scratch more often than FFTW 2 (in FFTW 2, planning Chris@19: e.g. one transform of size 1024 also created wisdom for all smaller Chris@19: powers of 2, but this no longer occurs). Chris@19: Chris@19:

FFTW 3 also has the new routine fftw_import_system_wisdom to Chris@19: import wisdom from a standard system-wide location. Chris@19: Chris@19:

Memory allocation

Chris@19: Chris@19:

In FFTW 3, we recommend allocating your arrays with fftw_malloc Chris@19: and deallocating them with fftw_free; this is not required, but Chris@19: allows optimal performance when SIMD acceleration is used. (Those two Chris@19: functions actually existed in FFTW 2, and worked the same way, but were Chris@19: not documented.) Chris@19: Chris@19:

In FFTW 2, there were fftw_malloc_hook and fftw_free_hook Chris@19: functions that allowed the user to replace FFTW's memory-allocation Chris@19: routines (e.g. to implement different error-handling, since by default Chris@19: FFTW prints an error message and calls exit to abort the program Chris@19: if malloc returns NULL). These hooks are not supported in Chris@19: FFTW 3; those few users who require this functionality can just Chris@19: directly modify the memory-allocation routines in FFTW (they are defined Chris@19: in kernel/alloc.c). Chris@19: Chris@19:

Fortran interface

Chris@19: Chris@19:

In FFTW 2, the subroutine names were obtained by replacing ‘fftw_’ Chris@19: with ‘fftw_f77’; in FFTW 3, you replace ‘fftw_’ with Chris@19: ‘dfftw_’ (or ‘sfftw_’ or ‘lfftw_’, depending upon the Chris@19: precision). Chris@19: Chris@19:

In FFTW 3, we have begun recommending that you always declare the type Chris@19: used to store plans as integer*8. (Too many people didn't notice Chris@19: our instruction to switch from integer to integer*8 for Chris@19: 64-bit machines.) Chris@19: Chris@19:

In FFTW 3, we provide a fftw3.f “header file” to include in Chris@19: your code (and which is officially installed on Unix systems). (In FFTW Chris@19: 2, we supplied a fftw_f77.i file, but it was not installed.) Chris@19: Chris@19:

Otherwise, the C-Fortran interface relationship is much the same as it Chris@19: was before (e.g. return values become initial parameters, and Chris@19: multi-dimensional arrays are in column-major order). Unlike FFTW 2, we Chris@19: do provide some support for wisdom import/export in Fortran Chris@19: (see Wisdom of Fortran?). Chris@19: Chris@19:

Threads

Chris@19: Chris@19:

Like FFTW 2, only the execution routines are thread-safe. All planner Chris@19: routines, etcetera, should be called by only a single thread at a time Chris@19: (see Thread safety). Unlike FFTW 2, there is no special Chris@19: FFTW_THREADSAFE flag for the planner to allow a given plan to be Chris@19: usable by multiple threads in parallel; this is now the case by default. Chris@19: Chris@19:

The multi-threaded version of FFTW 2 required you to pass the number of Chris@19: threads each time you execute the transform. The number of threads is Chris@19: now stored in the plan, and is specified before the planner is called by Chris@19: fftw_plan_with_nthreads. The threads initialization routine used Chris@19: to be called fftw_threads_init and would return zero on success; Chris@19: the new routine is called fftw_init_threads and returns zero on Chris@19: failure. See Multi-threaded FFTW. Chris@19: Chris@19:

There is no separate threads header file in FFTW 3; all the function Chris@19: prototypes are in <fftw3.h>. However, you still have to link to Chris@19: a separate library (-lfftw3_threads -lfftw3 -lm on Unix), as well as Chris@19: to the threading library (e.g. POSIX threads on Unix). Chris@19: Chris@19:

Chris@19:
Chris@19:

Footnotes

[1] We Chris@19: do our own buffering because GNU libc I/O routines are horribly slow for Chris@19: single-character I/O, apparently for thread-safety reasons (whether you Chris@19: are using threads or not).

Chris@19: Chris@19:
Chris@19: Chris@19: Chris@19: