@node Upgrading from FFTW version 2, Installation and Customization, Calling FFTW from Legacy Fortran, Top @chapter 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 @code{} header file. @heading Numeric Types The main difference in data types is that @code{fftw_complex} in FFTW 2 was defined as a @code{struct} with macros @code{c_re} and @code{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: @example #define c_re(c) ((c)[0]) #define c_im(c) ((c)[1]) @end example This does not work if you are using the C99 complex type, however, unless you insert a @code{double*} typecast into the above macros (@pxref{Complex numbers}). Also, FFTW 2 had an @code{fftw_real} typedef that was an alias for @code{double} (in double precision). In FFTW 3 you should just use @code{double} (or whatever precision you are employing). @heading 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 @emph{any} arrays and for @emph{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 @emph{those} arrays (unless the guru interface is used) and @emph{those} parameters @emph{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 @code{FFTW_ESTIMATE}. FFTW 2 had separate data types @code{fftw_plan}, @code{fftwnd_plan}, @code{rfftw_plan}, and @code{rfftwnd_plan} for complex and real one- and multi-dimensional transforms, and each type had its own @samp{destroy} function. In FFTW 3, all plans are of type @code{fftw_plan} and all are destroyed by @code{fftw_destroy_plan(plan)}. Where you formerly used @code{fftw_create_plan} and @code{fftw_one} to plan and compute a single 1d transform, you would now use @code{fftw_plan_dft_1d} to plan the transform. If you used the generic @code{fftw} function to execute the transform with multiplicity (@code{howmany}) and stride parameters, you would now use the advanced interface @code{fftw_plan_many_dft} to specify those parameters. The plans are now executed with @code{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 @code{FFTW_IN_PLACE} flag. You simply pass the same pointer for both the input and output arguments. (Previously, the output @code{ostride} and @code{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 @code{FFTW_ESTIMATE} and @code{FFTW_MEASURE} flags have the same meaning as before, although the planning time will differ. You may also consider using @code{FFTW_PATIENT}, which is like @code{FFTW_MEASURE} except that it takes more time in order to consider a wider variety of algorithms. For multi-dimensional complex DFTs, instead of @code{fftwnd_create_plan} (or @code{fftw2d_create_plan} or @code{fftw3d_create_plan}), followed by @code{fftwnd_one}, you would use @code{fftw_plan_dft} (or @code{fftw_plan_dft_2d} or @code{fftw_plan_dft_3d}). followed by @code{fftw_execute}. If you used @code{fftwnd} to to specify strides etcetera, you would instead specify these via @code{fftw_plan_many_dft}. The analogues to @code{rfftw_create_plan} and @code{rfftw_one} with @code{FFTW_REAL_TO_COMPLEX} or @code{FFTW_COMPLEX_TO_REAL} directions are @code{fftw_plan_r2r_1d} with kind @code{FFTW_R2HC} or @code{FFTW_HC2R}, followed by @code{fftw_execute}. The stride etcetera arguments of @code{rfftw} are now in @code{fftw_plan_many_r2r}. Instead of @code{rfftwnd_create_plan} (or @code{rfftw2d_create_plan} or @code{rfftw3d_create_plan}) followed by @code{rfftwnd_one_real_to_complex} or @code{rfftwnd_one_complex_to_real}, you now use @code{fftw_plan_dft_r2c} (or @code{fftw_plan_dft_r2c_2d} or @code{fftw_plan_dft_r2c_3d}) or @code{fftw_plan_dft_c2r} (or @code{fftw_plan_dft_c2r_2d} or @code{fftw_plan_dft_c2r_3d}), respectively, followed by @code{fftw_execute}. As usual, the strides etcetera of @code{rfftwnd_real_to_complex} or @code{rfftwnd_complex_to_real} are no specified in the advanced planner routines, @code{fftw_plan_many_dft_r2c} or @code{fftw_plan_many_dft_c2r}. @heading Wisdom In FFTW 2, you had to supply the @code{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 @code{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.@footnote{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).} 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 @code{fftw_import_system_wisdom} to import wisdom from a standard system-wide location. @heading Memory allocation In FFTW 3, we recommend allocating your arrays with @code{fftw_malloc} and deallocating them with @code{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 @code{fftw_malloc_hook} and @code{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 @code{exit} to abort the program if @code{malloc} returns @code{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 @code{kernel/alloc.c}). @heading Fortran interface In FFTW 2, the subroutine names were obtained by replacing @samp{fftw_} with @samp{fftw_f77}; in FFTW 3, you replace @samp{fftw_} with @samp{dfftw_} (or @samp{sfftw_} or @samp{lfftw_}, depending upon the precision). In FFTW 3, we have begun recommending that you always declare the type used to store plans as @code{integer*8}. (Too many people didn't notice our instruction to switch from @code{integer} to @code{integer*8} for 64-bit machines.) In FFTW 3, we provide a @code{fftw3.f} ``header file'' to include in your code (and which is officially installed on Unix systems). (In FFTW 2, we supplied a @code{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 (@pxref{Wisdom of Fortran?}). @heading 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 (@pxref{Thread safety}). @emph{Unlike} FFTW 2, there is no special @code{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 @code{fftw_plan_with_nthreads}. The threads initialization routine used to be called @code{fftw_threads_init} and would return zero on success; the new routine is called @code{fftw_init_threads} and returns zero on failure. The current number of threads used by the planner can be checked with @code{fftw_planner_nthreads}. @xref{Multi-threaded FFTW}. There is no separate threads header file in FFTW 3; all the function prototypes are in @code{}. However, you still have to link to a separate library (@code{-lfftw3_threads -lfftw3 -lm} on Unix), as well as to the threading library (e.g. POSIX threads on Unix).