comparison src/fftw-3.3.3/doc/upgrading.texi @ 10:37bf6b4a2645

Add FFTW3

+@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{<fftw3.h>} 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.  @xref{Multi-threaded FFTW}.
+
+There is no separate threads header file in FFTW 3; all the function
+prototypes are in @code{<fftw3.h>}.  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).
+