Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 2021.1
  • 12/04/2020
  • Public Content
Contents

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.h
header 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
    (
    float
     and
    double
    , respectively)
    . 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
     header file.
    This file is
    borrowed from the FFTW3.x package and distributed within
    Intel® oneAPI Math Kernel Library
     with permission. Additionally, the
    fftw3_mkl.h
     header file define
    s
     supporting structures and supplementary constants and macros.
  • 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
    .
  • The FFTW3 wrappers to
    Intel® oneAPI Math Kernel Library
     use the 32-bit
    int
    type in both LP64 and ILP64 interfaces of
    Intel® oneAPI Math Kernel Library
    . Use guru64 FFTW3 interfaces for 64-bit sizes.
  • 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_DLL
    with 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.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.