Using FFTW3 Wrappers

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 11/07/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-D17B3AB4-BD4E-4652-94A7-BAD4130CCB4A

View Details

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 (oneMKL).

The FFTW3 wrappers do not support long double precision because Intel® oneAPI Math Kernel Library (oneMKL) 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 (oneMKL) with permission. Additionally, the fftw3_mkl.h header file defines 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 (oneMKL) use the 32-bit int type in both LP64 and ILP64 interfaces of Intel® oneAPI Math Kernel Library (oneMKL). 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 (oneMKL).
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 FFTW3 wrapper library or Intel® oneAPI Math Kernel Library (oneMKL) in your link line application. All libraries define "fftw_destroy_plan" symbol and linkage in incorrect order results into expected errors.

Parent topic: FFTW3 Interface to Intel® oneAPI Math Kernel Library

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for C

Using FFTW3 Wrappers