Using FFTW3 Wrappers

The FFTW3 wrappers are a set of functions and data structures depending on one another. The wrappers are not designed to provide the interface on a function-per-function basis. Some FFTW3 wrapper functions are empty and do nothing, but they are present to avoid link errors and satisfy function calls.

This document does not list the declarations of the functions that the FFTW3 wrappers provide (you can find the declarations in the fftw3.hheader file). Instead, this section comments on particular limitations of the wrappers and provides usage hints:. These are some known limitations of FFTW3 wrappers and their usage in Intel® oneAPI Math Kernel Library.

• The FFTW3 wrappers do not support long double precision because Intel® oneAPI Math Kernel Library FFT functions operate only on single- and double-precision floating-point data types. Therefore the functions with prefix fftwl_, supporting the long double data type, are not provided.

• The wrappers provide equivalent implementation for double- and single-precision functions (those with prefixes fftw_ and fftwf_, respectively). So, all these comments equally apply to the double- and single-precision functions and will refer to functions with prefix fftw_, that is, double-precision functions, for brevity.

• The FFTW3 interface that the wrappers provide is defined in the fftw3.h and fftw3.f header files. These files areborrowed from the FFTW3.x package and distributed within Intel® oneAPI Math Kernel Library with permission. Additionally, thefftw3_mkl.h, fftw3_mkl.f, and fftw3_mkl_f77.h header files define supporting structures and supplementary constants and macros, as well as expose Fortran interface in C.

• Actual functionality of the plan creation wrappers is implemented in guru64 set of functions. Basic interface, advanced interface, and guru interface plan creation functions call the guru64 interface functions. So, all types of the FFTW3 plan creation interface in the wrappers are functional.

• Plan creation functions may return a NULL plan, indicating that the functionality is not supported. So, please carefully check the result returned by plan creation functions in your application. In particular, the following problems return a NULL plan:

  • c2r and r2c problems with a split storage of complex data.

  • r2r problems with kind values FFTW_R2HC, FFTW_HC2R, and FFTW_DHT. The only supported r2r kinds are even/odd DFTs (sine/cosine transforms).

  • Multidimensional r2r transforms.

  • Transforms of multidimensional vectors. That is, the only supported values for parameter howmany_rank in guru and guru64 plan creation functions are 0 and 1.

  • Multidimensional transforms with rank > MKL_MAXRANK.

• The MKL_RODFT00 value of the kind parameter is introduced by the FFTW3 wrappers. For better performance, you are strongly encouraged to use this value rather than FFTW_RODFT00. To use this kind value, provide an extra first element equal to 0.0 for the input/output vectors. Consider the following example:

  plan1 = fftw_plan_r2r_1d(n, in1, out1, FFTW_RODFT00, FFTW_ESTIMATE);
  plan2 = fftw_plan_r2r_1d(n, in2, out2, MKL_RODFT00, FFTW_ESTIMATE);
   

  Both plans perform the same transform, except that the in2/out2 arrays have one extra zero element at location 0. For example, if n=3, in1={x,y,z} and out1={u,v,w}, then in2={0,x,y,z} and out2={0,u,v,w}.

• The flags parameter in plan creation functions is always ignored. The same algorithm is used regardless of the value of this parameter. In particular, flags values FFTW_ESTIMATE, FFTW_MEASURE, etc. have no effect.

• For multithreaded plans, use normal sequence of calls to the fftw_init_threads() and fftw_plan_with_nthreads() functions (refer to FFTW documentation).

• Memory allocation function fftw_malloc returns memory aligned at a 16-byte boundary. You must free the memory with fftw_free.

• Fortran wrappers (see Calling Wrappers from Fortran) use the INTEGER type, which is 32-bit in LP64 interfaces and 64-bit in ILP64 interfaces.

• The wrappers typically indicate a problem by returning a NULL plan. In a few cases, the wrappers may report a descriptive message of the problem detected. By default the reporting is turned off. To turn it on, set variable fftw3_mkl.verbose to a non-zero value, for example:

  #include "fftw3.h"
  #include "fftw3_mkl.h"
  fftw3_mkl.verbose = 0;
  plan = fftw_plan_r2r(...);
   

• The following functions are empty:

  • For saving, loading, and printing plans

  • For saving and loading wisdom

  • For estimating arithmetic cost of the transforms.

• Do not use macro FFTW_DLLwith the FFTW3 wrappers to Intel® oneAPI Math Kernel Library.

• Do not use negative stride values. Though FFTW3 wrappers support negative strides in the part of advanced and guru FFTW interface, the underlying implementation does not.

• Do not set a FFTW2 wrapper library before a FFT23 wrapper library or Intel® oneAPI Math Kernel Library in your link line application. All libraries define "fftw_destroy_plan" symbol and linkage in incorrect order results into expected errors.