API reference¶

This section describes the supported FFTW APIs, with notes that highlight the differences between the NVPL FFT and the FFTW3 library, and an additional service API for getting version information of the NVPL FFT library.

Version Information¶

int nvpl_fft_get_version()¶

Parameters:

int – The version of NVPL FFT. Returns NVPL_FFT_VERSION, which is equivalent to NVPL_FFT_VERSION_MAJOR * 10000 + NVPL_FFT_VERSION_MINOR * 100 + NVPL_FFT_VERSION_PATCH.

Plan creation, execution and destruction¶

Warning

The planner flag flags argument is ignored in NVPL FFT and the same plan is returned regardless of its value.

Warning

The pointers to input and output data (in and out) provided either during plan creation or execution are required to be aligned to fftwf_complex data type in single precision transforms and fftw_complex type in double-precision transforms.

Basic plan interface¶

To create a fftw(f)_plan for computing DFTs with specified sign, sizes and types. This set of interface only supports single batch FFT execution with contiguous input and output data.

Complex input to complex output (C2C)¶

fftw_plan fftw_plan_dft_1d(int n0, fftw_complex *in, fftw_complex *out, int sign, unsigned flags)¶

fftw_plan fftw_plan_dft_2d(int n0, int n1, fftw_complex *in, fftw_complex *out, int sign, unsigned flags)¶

fftw_plan fftw_plan_dft_3d(int n0, int n1, int n2, fftw_complex *in, fftw_complex *out, int sign, unsigned flags)¶

fftw_plan fftw_plan_dft(int rank, const int *n, fftw_complex *in, fftw_complex *out, int sign, unsigned flags)¶

fftwf_plan fftwf_plan_dft_1d(int n0, fftwf_complex *in, fftwf_complex *out, int sign, unsigned flags);¶

fftwf_plan fftwf_plan_dft_2d(int n0, int n1, fftwf_complex *in, fftwf_complex *out, int sign, unsigned flags);¶

fftwf_plan fftwf_plan_dft_3d(int n0, int n1, int n2, fftwf_complex *in, fftwf_complex *out, int sign, unsigned flags);¶

fftwf_plan fftwf_plan_dft(int rank, const int *n, fftwf_complex *in, fftwf_complex *out, int sign, unsigned flags);¶

Parameters:

rank[in] – The dimension of the transform. It can be 1, 2 or 3.
n0[in] – The transform (input and output) size in the 0th dimension (outermost dimension).
n1[in] – The transform (input and output) size in the 1st dimension.
n2[in] – The transform (input and output) size in the 2nd dimension (innermost dimension).
n[in] – A pointer to an array of integers with size rank. n[i] is the transform size (input and output) in dimension i, i=0,...,rank-1. n[0] and n[rank-1] are the size for the outermost and innermost dimension, respectively.
in[in] – A pointer to input data.
out[out] – A pointer to output data. If value is the same as in, the transform will be done in-place.
sign[in] – The sign of the exponent in the DFT formula. It can be -1 (FFTW_FORWARD) or 1 (FFTW_INVERSE or FFTW_BACKWARD).
flags[in] – A planner flag. Available options are FFTW_ESTIMATE, FFTW_MEASURE, FFTW_PATIENT, FFTW_EXHAUSTIVE, FFTW_WISDOM_ONLY.

Return values:

fftw(f)_plan – The created fftw(f)_plan. nullptr if the plan creation failed.

Real input to complex output (R2C)¶

fftw_plan fftw_plan_dft_r2c_1d(int n0, double *in, fftw_complex *out, unsigned flags)¶

fftw_plan fftw_plan_dft_r2c_2d(int n0, int n1, double *in, fftw_complex *out, unsigned flags)¶

fftw_plan fftw_plan_dft_r2c_3d(int n0, int n1, int n2, double *in, fftw_complex *out, unsigned flags)¶

fftw_plan fftw_plan_dft_r2c(int rank, const int *n, double *in, fftw_complex *out, unsigned flags)¶

fftwf_plan fftwf_plan_dft_r2c_1d(int n0, float *in, fftwf_complex *out, unsigned flags)¶

fftwf_plan fftwf_plan_dft_r2c_2d(int n0, int n1, float *in, fftwf_complex *out, unsigned flags)¶

fftwf_plan fftwf_plan_dft_r2c_3d(int n0, int n1, int n2, float *in, fftwf_complex *out, unsigned flags)¶

fftwf_plan fftwf_plan_dft_r2c(int rank, const int *n, float *in, fftwf_complex *out, unsigned flags)¶

Parameters:

rank[in] – The dimension of the transform. It can be 1, 2 or 3.
n0[in] – The transform (input) size in the 0th dimension (outermost dimension).
n1[in] – The transform (input) size in the 1st dimension.
n2[in] – The transform (input) size in the 2nd dimension (innermost dimension).
n[in] – A pointer to an array of integers with size rank. n[i] is the transform (input) size in dimension i, i=0,...,rank-1. n[0] and n[rank-1] are the size for the outermost and innermost dimension, respectively.
in[in] – A pointer to input data.
out[out] – A pointer to output data. If value is the same as in, the transform will be done in-place.
sign[in] – The sign of the exponent in the DFT formula. It can be 1 (FFTW_INVERSE or FFTW_BACKWARD), -1 (FFTW_FORWARD)
flags[in] – A planner flag. Available options are FFTW_ESTIMATE, FFTW_MEASURE, FFTW_PATIENT, FFTW_EXHAUSTIVE, FFTW_WISDOM_ONLY.

Return values:

fftw(f)_plan – The created fftw(f)_plan. nullptr if the plan creation failed.

Note

For R2C transforms, unlike C2C ones, input and output sizes are different (specifically, in the innermost dimension). The n, n0, n1, n2 here are the sizes of the input data (i.e. the real data). See also Data Layout in the cuFFT documentation.

Complex input to real output (C2R)¶

fftw_plan fftw_plan_dft_c2r_1d(int n0, fftw_complex *in, double *out, unsigned flags)¶

fftw_plan fftw_plan_dft_c2r_2d(int n0, int n1, fftw_complex *in, double *out, unsigned flags)¶

fftw_plan fftw_plan_dft_c2r_3d(int n0, int n1, int n2, fftw_complex *in, double *out, unsigned flags)¶

fftw_plan fftw_plan_dft_c2r(int rank, const int *n, fftw_complex *in, double *out, unsigned flags)¶

fftwf_plan fftwf_plan_dft_c2r_1d(int n0, fftwf_complex *in, float *out, unsigned flags)¶

fftwf_plan fftwf_plan_dft_c2r_2d(int n0, int n1, fftwf_complex *in, float *out, unsigned flags)¶

fftwf_plan fftwf_plan_dft_c2r_3d(int n0, int n1, int n2, fftwf_complex *in, float *out, unsigned flags)¶

fftwf_plan fftwf_plan_dft_c2r(int rank, const int *n, fftwf_complex *in, float *out, unsigned flags)¶

Parameters:

rank[in] – The dimension of the transform. It can be 1, 2 or 3.
n0[in] – The transform (output) size in the 0th dimension (outermost dimension).
n1[in] – The transform (output) size in the 1st dimension.
n2[in] – The transform (output) size in the 2nd dimension (innermost dimension).
n[in] – A pointer to an array of integers with size rank. n[i] is the transform (output) size in dimension i, i=0,...,rank-1. n[0] and n[rank-1] are the size for the outermost and innermost dimension, respectively.
in[in] – A pointer to input data.
out[out] – A pointer to output data. If value is the same as in, the transform will be done in-place.
sign[in] – The sign of the exponent in the DFT formula. It can be 1 (FFTW_INVERSE or FFTW_BACKWARD), -1 (FFTW_FORWARD)
flags[in] – A planner flag. Available options are FFTW_ESTIMATE, FFTW_MEASURE, FFTW_PATIENT, FFTW_EXHAUSTIVE, FFTW_WISDOM_ONLY.

Return values:

fftw(f)_plan – The created fftw(f)_plan. nullptr if the plan creation failed.

Note

Similarly to R2C, for C2R transforms, the input and output sizes are different (specifically, in the innermost dimension). The n, n0, n1, n2 here are the sizes of the output data. See also Data Layout in the cuFFT documentation.

Note

As pointed out in Fourier transform type in the cuFFT documentation, C2R transforms accept complex-Hermitian input. This implies that in the innermost dimension, the 0th element and if n[rank-1] is even, the n[rank-1]/2 th element need to be real-valued. If the requirement is not satisfied, the behavior of the transform is undefined.

Warning

Real-to-Real Transforms are not supported yet.

Advanced plan interface¶

To create a fftw(f)_plan for computing DFTs with specified dimension, sign, sizes, types and strides. It allows batched FFTs execution with contiguous or strided input and output data.

fftw_plan fftw_plan_many_dft(int rank, const int *n, int batch, fftw_complex *in, const int *inembed, int istride, int idist, fftw_complex *out, const int *onembed, int ostride, int odist, int sign, unsigned flags)¶

fftw_plan fftw_plan_many_dft_r2c(int rank, const int *n, int batch, double *in, const int *inembed, int istride, int idist, fftw_complex *out, const int *onembed, int ostride, int odist, unsigned flags)¶

fftw_plan fftw_plan_many_dft_c2r(int rank, const int *n, int batch, fftw_complex *in, const int *inembed, int istride, int idist, double *out, const int *onembed, int ostride, int odist, unsigned flags)¶

fftwf_plan fftwf_plan_many_dft(int rank, const int *n, int batch, fftwf_complex *in, const int *inembed, int istride, int idist, fftwf_complex *out, const int *onembed, int ostride, int odist, int sign, unsigned flags)¶

fftwf_plan fftwf_plan_many_dft_r2c(int rank, const int *n, int batch, double *in, const int *inembed, int istride, int idist, fftwf_complex *out, const int *onembed, int ostride, int odist, unsigned flags)¶

fftwf_plan fftwf_plan_many_dft_c2r(int rank, const int *n, int batch, fftwf_complex *in, const int *inembed, int istride, int idist, double *out, const int *onembed, int ostride, int odist, unsigned flags)¶

Parameters:

rank[in] – The dimension of the transform.
n[in] – A pointer to an array of integers with size rank. n[i] is the transform (output) size in dimension i, i=0,...,rank-1. n[0] and n[rank-1] are the size for the outermost and innermost dimension, respectively.
batch[in] – Number of batches of DFTs to be computed.
inembed[in] – nullptr or a pointer to an array of integers with size rank. inembed[i] is the number of element in dimension i of the input data, i=0,...,rank-1.
istride[in] – The distance between two consecutive input elements in the innermost dimension.
idist[in] – The distance between the first element of two consecutive batches in the input data.
onembed[in] – nullptr or a pointer to an array of integers with size rank. onembed[i] is the number of element in dimension i of the output data, i=0,...,rank-1.
ostride[in] – The distance between two consecutive output elements in the innermost dimension.
odist[in] – The distance between the first element of two consecutive batches in the output data.
in[in] – A pointer to input data.
out[out] – A pointer to output data. If value is the same as in, the transform will be done in-place.
sign[in] – The sign of the exponent in the DFT formula. It can be 1 (FFTW_INVERSE or FFTW_BACKWARD), -1 (FFTW_FORWARD)
flags[in] – A planner flag. Available options are FFTW_ESTIMATE, FFTW_MEASURE, FFTW_PATIENT, FFTW_EXHAUSTIVE, FFTW_WISDOM_ONLY.

Return values:

fftw(f)_plan – The created fftw(f)_plan. nullptr if the plan creation failed.

Warning

Planning with four or higher dimensional transforms is not supported yet, i.e., we require rank less than or equal to 3.

Note

Passing nullptr for inembed and onembed is equivalent to passing arrays of integers with values being the number of input and output elements in each dimension for inembed and onembed, respectively. For C2C transforms, this means passing n for both inembed and onembed.

Warning

Guru plan interfaces exist but are not functional yet. nullptr will always be returned by the APIs.

Execute interface¶

To execute a fftw(f)_plan.

void fftw_execute(const fftw_plan plan)¶

void fftwf_execute(const fftwf_plan plan)¶

This function uses the input and output data that are passed in as arguments during plan creation.

Parameters:

plan[in] – A fftw(f)_plan created by plan creation APIs.

void fftw_execute_dft(const fftw_plan plan, fftw_complex *idata, fftw_complex *odata)¶

void fftw_execute_dft_r2c(const fftw_plan plan, double *idata, fftw_complex *odata)¶

void fftw_execute_dft_c2r(const fftw_plan plan, fftwf_complex *idata, double *odata)¶

void fftwf_execute_dft(const fftwf_plan plan, fftwf_complex *idata, fftwf_complex *odata)¶

void fftwf_execute_dft_r2c(const fftwf_plan plan, float *idata, fftwf_complex *odata)¶

void fftwf_execute_dft_c2r(const fftwf_plan plan, fftwf_complex *idata, float *odata)¶

These functions ignore the input and output data that are passed in as arguments during plan creation and use the input and output data passed in here.

Parameters:

plan[in] – A fftw(f)_plan created by plan creation APIs.
idata[in] – A pointer to input data. The data type depends on the type of transforms.
odata[out] – A pointer to output data, i.e. the DFTs results. Same as idata, the data type depends on the type of transforms.

Note

idata and odata need to be consistent with fftw(f)_plan regarding in-place or out-of-place transforms, i.e. if fftw(f)_plan is created with in = out, then idata = odata is required.

Destruction interface¶

To free all resources associated with a fftw(f)_plan.

void fftw_destroy_plan(fftw_plan plan)¶

void fftwf_destroy_plan(fftw_plan plan)¶

Parameters:

plan[in] – The fftw(f)_plan to be destroyed.

Thread control¶

Warning

For thread control, NVPL FFT follows the design in FFTW. See also Usage of Multi-threaded FFTW in the FFTW3 documentation.

int fftw_init_threads(void)¶

int fftwf_init_threads(void)¶

To perform one-time initalization for using threads on the system.

Return values:: int – A non-zero value if the initialization is successfully done and 0 if not.

Warning

Not required for using multi-threaded implementations of NVPL FFT.

void fftw_plan_with_nthreads(int nthreads)¶

void fftwf_plan_with_nthreads(int nthreads)¶

To set the number of threads that are going to be used in the fftw(f)_plan. Please note that setting the number of threads only impacts plans created after this function is called; it does not change the behavior of plans created prior to calling fftw(f)_init_nthreads.

Parameters:

nthreads[in] – Number of threads to be used for the fftw(f)_plan (s) created afterward.

Note

If fftw(f)_plan_with_nthreads is not called, or called with nthreads = 1 in an application, single-threaded implementations will be used.

int fftw_planner_nthreads(void)¶

int fftwf_planner_nthreads(void)¶

To determine the number of threads that a fftw(f)_plan can use.

Return values:: int – Number of threads that will be used in the fftw(f)_plan (s) created afterward.

void fftw_cleanup_threads(void)¶

void fftwf_cleanup_threads(void)¶: Similar to fftw(f)_cleanup() but for cleaning up thread related data.

Warning

This function does not do any work in the NVPL FFT implementation and it is safe to not to call it.

Other¶

Warning

The APIs in this section exist but are not functional, i.e. the output parameters are set to some dummy values or success status values are returned. For the wisdom related functions, the same plan is returned by the plan creation APIs no matter whether they are called or not.

void fftw_cleanup(void)¶

void fftwf_cleanup(void)¶

void fftw_print_plan(const fftw_plan plan)¶

void fftwf_print_plan(const fftwf_plan plan)¶

Parameters:

plan[in] – A fftw(f)_plan created by plan creation APIs.

void fftw_set_timelimit(double seconds)¶

void fftwf_set_timelimit(double seconds)¶

Parameters:

second[in] – The time limit for plan creation.

double fftw_cost(const fftw_plan plan)¶

double fftwf_cost(const fftw_plan plan)¶

Parameters:

plan[in] – A fftw(f)_plan created by plan creation APIs.

Return values:

double – Always returns 1.0.

void fftw_flops(const fftw_plan plan, double *add, double *mul, double *fma)¶

void fftwf_flops(const fftwf_plan plan, double *add, double *mul, double *fma)¶

Parameters:

plan[in] – A fftw(f)_plan created by plan creation APIs.
add[out] – Always set to 1.0.
mul[out] – Always set to 1.0.
fma[out] – Always set to 1.0.

Wisdom interface¶

To export, import, forget wisdom in the supported formats. See Wisdom in the FFTW3 documentation.

void fftw_export_wisdom(void (*write_char)(char c, void*), void *data)¶

void fftw_export_wisdom_to_file(FILE *output_file)¶

char *fftw_export_wisdom_to_string(void)¶

int fftw_import_wisdom(int (*read_char)(void*), void *data)¶

int fftw_import_wisdom_from_file(FILE *input_file)¶

int fftw_import_wisdom_from_string(const char *input_string)¶

int fftw_import_system_wisdom(void)¶

void fftw_forget_wisdom(void)¶

void fftwf_export_wisdom(void (*write_char)(char c, void*), void *data)¶

void fftwf_export_wisdom_to_file(FILE *output_file)¶

char *fftwf_export_wisdom_to_string(void)¶

int fftwf_import_wisdom(int (*read_char)(void*), void *data)¶

int fftwf_import_wisdom_from_file(FILE *input_file)¶

int fftwf_import_wisdom_from_string(const char *input_string)¶

int fftwf_import_system_wisdom(void)¶

void fftwf_forget_wisdom(void)¶