fftw3: Upgrading from FFTW version 2
9 Upgrading from FFTW version 2
*******************************
In this chapter, we outline the process for updating codes designed for
the older FFTW 2 interface to work with FFTW 3. The interface for FFTW
3 is not backwards-compatible with the interface for FFTW 2 and earlier
versions; codes written to use those versions will fail to link with
FFTW 3. Nor is it possible to write "compatibility wrappers" to bridge
the gap (at least not efficiently), because FFTW 3 has different
semantics from previous versions. However, upgrading should be a
straightforward process because the data formats are identical and the
overall style of planning/execution is essentially the same.
Unlike FFTW 2, there are no separate header files for real and
complex transforms (or even for different precisions) in FFTW 3; all
interfaces are defined in the '<fftw3.h>' header file.
Numeric Types
=============
The main difference in data types is that 'fftw_complex' in FFTW 2 was
defined as a 'struct' with macros 'c_re' and 'c_im' for accessing the
real/imaginary parts. (This is binary-compatible with FFTW 3 on any
machine except perhaps for some older Crays in single precision.) The
equivalent macros for FFTW 3 are:
#define c_re(c) ((c)[0])
#define c_im(c) ((c)[1])
This does not work if you are using the C99 complex type, however,
unless you insert a 'double*' typecast into the above macros (
Complex numbers).
Also, FFTW 2 had an 'fftw_real' typedef that was an alias for
'double' (in double precision). In FFTW 3 you should just use 'double'
(or whatever precision you are employing).
Plans
=====
The major difference between FFTW 2 and FFTW 3 is in the
planning/execution division of labor. In FFTW 2, plans were found for a
given transform size and type, and then could be applied to _any_ arrays
and for _any_ multiplicity/stride parameters. In FFTW 3, you specify
the particular arrays, stride parameters, etcetera when creating the
plan, and the plan is then executed for _those_ arrays (unless the guru
interface is used) and _those_ parameters _only_. (FFTW 2 had "specific
planner" routines that planned for a particular array and stride, but
the plan could still be used for other arrays and strides.) That is,
much of the information that was formerly specified at execution time is
now specified at planning time.
Like FFTW 2's specific planner routines, the FFTW 3 planner
overwrites the input/output arrays unless you use 'FFTW_ESTIMATE'.
FFTW 2 had separate data types 'fftw_plan', 'fftwnd_plan',
'rfftw_plan', and 'rfftwnd_plan' for complex and real one- and
multi-dimensional transforms, and each type had its own 'destroy'
function. In FFTW 3, all plans are of type 'fftw_plan' and all are
destroyed by 'fftw_destroy_plan(plan)'.
Where you formerly used 'fftw_create_plan' and 'fftw_one' to plan and
compute a single 1d transform, you would now use 'fftw_plan_dft_1d' to
plan the transform. If you used the generic 'fftw' function to execute
the transform with multiplicity ('howmany') and stride parameters, you
would now use the advanced interface 'fftw_plan_many_dft' to specify
those parameters. The plans are now executed with 'fftw_execute(plan)',
which takes all of its parameters (including the input/output arrays)
from the plan.
In-place transforms no longer interpret their output argument as
scratch space, nor is there an 'FFTW_IN_PLACE' flag. You simply pass
the same pointer for both the input and output arguments. (Previously,
the output 'ostride' and 'odist' parameters were ignored for in-place
transforms; now, if they are specified via the advanced interface, they
are significant even in the in-place case, although they should normally
equal the corresponding input parameters.)
The 'FFTW_ESTIMATE' and 'FFTW_MEASURE' flags have the same meaning as
before, although the planning time will differ. You may also consider
using 'FFTW_PATIENT', which is like 'FFTW_MEASURE' except that it takes
more time in order to consider a wider variety of algorithms.
For multi-dimensional complex DFTs, instead of 'fftwnd_create_plan'
(or 'fftw2d_create_plan' or 'fftw3d_create_plan'), followed by
'fftwnd_one', you would use 'fftw_plan_dft' (or 'fftw_plan_dft_2d' or
'fftw_plan_dft_3d'). followed by 'fftw_execute'. If you used 'fftwnd'
to to specify strides etcetera, you would instead specify these via
'fftw_plan_many_dft'.
The analogues to 'rfftw_create_plan' and 'rfftw_one' with
'FFTW_REAL_TO_COMPLEX' or 'FFTW_COMPLEX_TO_REAL' directions are
'fftw_plan_r2r_1d' with kind 'FFTW_R2HC' or 'FFTW_HC2R', followed by
'fftw_execute'. The stride etcetera arguments of 'rfftw' are now in
'fftw_plan_many_r2r'.
Instead of 'rfftwnd_create_plan' (or 'rfftw2d_create_plan' or
'rfftw3d_create_plan') followed by 'rfftwnd_one_real_to_complex' or
'rfftwnd_one_complex_to_real', you now use 'fftw_plan_dft_r2c' (or
'fftw_plan_dft_r2c_2d' or 'fftw_plan_dft_r2c_3d') or 'fftw_plan_dft_c2r'
(or 'fftw_plan_dft_c2r_2d' or 'fftw_plan_dft_c2r_3d'), respectively,
followed by 'fftw_execute'. As usual, the strides etcetera of
'rfftwnd_real_to_complex' or 'rfftwnd_complex_to_real' are no specified
in the advanced planner routines, 'fftw_plan_many_dft_r2c' or
'fftw_plan_many_dft_c2r'.
Wisdom
======
In FFTW 2, you had to supply the 'FFTW_USE_WISDOM' flag in order to use
wisdom; in FFTW 3, wisdom is always used. (You could simulate the FFTW
2 wisdom-less behavior by calling 'fftw_forget_wisdom' after every
planner call.)
The FFTW 3 wisdom import/export routines are almost the same as
before (although the storage format is entirely different). There is
one significant difference, however. In FFTW 2, the import routines
would never read past the end of the wisdom, so you could store extra
data beyond the wisdom in the same file, for example. In FFTW 3, the
file-import routine may read up to a few hundred bytes past the end of
the wisdom, so you cannot store other data just beyond it.(1)
Wisdom has been enhanced by additional humility in FFTW 3: whereas
FFTW 2 would re-use wisdom for a given transform size regardless of the
stride etc., in FFTW 3 wisdom is only used with the strides etc. for
which it was created. Unfortunately, this means FFTW 3 has to create
new plans from scratch more often than FFTW 2 (in FFTW 2, planning e.g.
one transform of size 1024 also created wisdom for all smaller powers of
2, but this no longer occurs).
FFTW 3 also has the new routine 'fftw_import_system_wisdom' to import
wisdom from a standard system-wide location.
Memory allocation
=================
In FFTW 3, we recommend allocating your arrays with 'fftw_malloc' and
deallocating them with 'fftw_free'; this is not required, but allows
optimal performance when SIMD acceleration is used. (Those two
functions actually existed in FFTW 2, and worked the same way, but were
not documented.)
In FFTW 2, there were 'fftw_malloc_hook' and 'fftw_free_hook'
functions that allowed the user to replace FFTW's memory-allocation
routines (e.g. to implement different error-handling, since by default
FFTW prints an error message and calls 'exit' to abort the program if
'malloc' returns 'NULL'). These hooks are not supported in FFTW 3;
those few users who require this functionality can just directly modify
the memory-allocation routines in FFTW (they are defined in
'kernel/alloc.c').
Fortran interface
=================
In FFTW 2, the subroutine names were obtained by replacing 'fftw_' with
'fftw_f77'; in FFTW 3, you replace 'fftw_' with 'dfftw_' (or 'sfftw_' or
'lfftw_', depending upon the precision).
In FFTW 3, we have begun recommending that you always declare the
type used to store plans as 'integer*8'. (Too many people didn't notice
our instruction to switch from 'integer' to 'integer*8' for 64-bit
machines.)
In FFTW 3, we provide a 'fftw3.f' "header file" to include in your
code (and which is officially installed on Unix systems). (In FFTW 2,
we supplied a 'fftw_f77.i' file, but it was not installed.)
Otherwise, the C-Fortran interface relationship is much the same as
it was before (e.g. return values become initial parameters, and
multi-dimensional arrays are in column-major order). Unlike FFTW 2, we
do provide some support for wisdom import/export in Fortran (
Wisdom of Fortran?).
Threads
=======
Like FFTW 2, only the execution routines are thread-safe. All planner
routines, etcetera, should be called by only a single thread at a time
(Thread safety). _Unlike_ FFTW 2, there is no special
'FFTW_THREADSAFE' flag for the planner to allow a given plan to be
usable by multiple threads in parallel; this is now the case by default.
The multi-threaded version of FFTW 2 required you to pass the number
of threads each time you execute the transform. The number of threads
is now stored in the plan, and is specified before the planner is called
by 'fftw_plan_with_nthreads'. The threads initialization routine used
to be called 'fftw_threads_init' and would return zero on success; the
new routine is called 'fftw_init_threads' and returns zero on failure.
Multi-threaded FFTW.
There is no separate threads header file in FFTW 3; all the function
prototypes are in '<fftw3.h>'. However, you still have to link to a
separate library ('-lfftw3_threads -lfftw3 -lm' on Unix), as well as to
the threading library (e.g. POSIX threads on Unix).
---------- Footnotes ----------
(1) We do our own buffering because GNU libc I/O routines are
horribly slow for single-character I/O, apparently for thread-safety
reasons (whether you are using threads or not).
Info Catalog
fftw3: Calling FFTW from Legacy Fortran
fftw3: Top
fftw3: Installation and Customization