hipFFTW API usage

This section describes how to use the hipFFTW library API. The hipFFTW API is a partial reproduction of the FFTW API.

Data types

Similarly to FFTW, hipFFTW uses the following specific types.

typedef double fftw_complex[2]

Type for double-precision complex floating-point values.

Note

fftw_complex is defined equivalent to double complex in applications that include the standard complex.h prior to hipfft/hipfftw.h.

typedef float fftwf_complex[2]

Single-precision equivalent of fftw_complex.

typedef struct fftw_plan_s *fftw_plan

Type for double-precision hipFFTW plans.

typedef struct fftwf_plan_s *fftwf_plan

Single-precision equivalent of fftw_plan;.

typedef hipfftw_iodim fftw_iodim

Structure type describing lengths (or batch sizes) and input/output strides (or distances) along a dimension for generalized data layouts. Structure members are:

• n length (or batch size);

• is input stride (or distance);

• os output stride (or distance).

All the above members are of type int.

typedef hipfftw_iodim fftwf_iodim

This type is strictly equivalent to fftw_iodim.

typedef hipfftw_iodim64 fftw_iodim64

This structure type is the equivalent of fftw_iodim using ptrdiff_t for members’ type instead of int.

typedef hipfftw_iodim64 fftwf_iodim64

This type is strictly equivalent to fftw_iodim64.

Constant values

Flag values

All the hipFFTW plan creation functions request an unsigned flags argument. The value of that argument conditions what hipFFTW will consider when creating the requested plan. Valid values are bitwise OR of zero of more of the following constant values.

FFTW_MEASURE

Flag value allowing hipFFTW to compute (possibly many) FFTs at plan creation to find the optimal configuration, using the input and output data buffers set at plan creation (hence possibly overwriting data therein).

FFTW_DESTROY_INPUT

Flag value allowing an out-of-place hipFFTW plan to overwrite its input buffer data at execution.

FFTW_UNALIGNED

Flag value ruling out any alignment assumption for the input and output buffers to be used at plan execution.

FFTW_CONSERVE_MEMORY

Flag value instructing plans to prefer configurations minimizing their memory footprint.

FFTW_EXHAUSTIVE

Flag value equivalent to FFTW_PATIENT, enabling the largest possible set of plan configurations to be considered in the measurements.

FFTW_PRESERVE_INPUT

Flag value forbidding an out-of-place hipFFTW plan to overwrite its input buffer data at execution.

Note

This flag value is not supported for out-of-place multidimensional real inverse tranforms.

FFTW_PATIENT

Flag value equivalent to FFTW_MEASURE, enabling a larger-than-default set of plan configurations to be considered in the measurements.

FFTW_ESTIMATE

Flag value enforcing hipFFTW to use a heuristric when selecting the plan configuration, thereby ruling out measurements and leaving input and output buffers untouched.

FFTW_WISDOM_ONLY

Flag instructing hipFFTW to query the requested plan from an on-disk database file (“wisdom”). If not found therein, no plan is created.

Note

This flag value is not supported by hipFFTW.

Note

Even if seemingly accepted, flag values are currently ignored by hipFFTW. In particular, note that:

• no measurement is ever done at plan creation (plan configurations are chosen based on heuristics);

• preservation of input data is never guaranteed;

• requests for a minimized memory footprint are ignored;

with the current status of hipFFTW.

Sign values

The hipFFTW plan creation functions for complex transforms request an int sign argument. This argument determines whether the plan being created is meant to compute forward or backward (inverse) discrete Fourier transforms. Valid values of that argument are either of the following constant values.

FFTW_FORWARD

Exponent sign value to be used for forward discrete Fourier transforms.

FFTW_BACKWARD

Exponent sign value to be used for backward (inverse) discrete Fourier transforms.

Buffer management

hipFFTW supports the following buffer-management functions.

void *fftw_malloc(size_t n)

Allocates a data buffer accessible by the host.

Remark

The returned base address is at least 64-bit aligned.

Parameters:

n – [in] number of bytes desired for the buffer.

Returns:

a pointer to the base address of the allocated memory block upon success (nullptr otherwise).

void *fftwf_malloc(size_t n)

This function is strictly equivalent to fftw_malloc.

double *fftw_alloc_real(size_t n)

This function is strictly equivalent to (double*) fftw_malloc(n * sizeof(double))

float *fftwf_alloc_real(size_t n)

This function is strictly equivalent to (float*) fftw_malloc(n * sizeof(float))

fftw_complex *fftw_alloc_complex(size_t n)

This function is strictly equivalent to (fftw_complex*) fftw_malloc(n * sizeof(fftw_complex))

fftwf_complex *fftwf_alloc_complex(size_t n)

This function is strictly equivalent to (fftwf_complex*) fftw_malloc(n * sizeof(fftwf_complex))

void fftw_free(void *p)

Frees a buffer previously allocated by any of the allocation functions above.

Parameters:

p – [in] pointer to the base address of the buffer to be freed.

void fftwf_free(void *p)

This function is strictly equivalent to fftw_free.

The memory blocks allocated by any of the above {fftw,fftwf}_{malloc,alloc_real,alloc_complex} are always directly accessible to the host, but not necessarily to the GPU. hipFFTW decides on the type of memory being allocated following a ranked-choice strategy. It attempts to allocate:

1. pinned host memory (first);

2. pageable host memory (if the latter failed or if the request exceeds a user-defined threshold).

Important

Every buffer allocated via fftw_malloc, fftwf_malloc, fftw_alloc_real, fftwf_alloc_real, fftw_alloc_complex, or fftwf_alloc_complex must be freed using fftw_free or fftwf_free.

Plan creation

hipFFTW supports the creation of basic, advanced, and general plans, using interleaved formats for complex floating-point data. Plans capture:

• the type of transform, namely, complex or real, forward or backward (inverse) discrete Fourier transform;

• the length(s) and batch size(s) of the transform;

• layout information for input and output data, for example, stride(s), distance(s);

• pointers to buffers that it should consider as input and output data buffers when computing a transform via a generic execution function;

• the flag value(s) to use at creation.

A plan of interest can be created using more than one plan creation function. For instance, any plan created by fftw_plan_dft (or fftwf_plan_dft) could be created by fftw_plan_many_dft (or fftwf_plan_many_dft) without any difference.

For all plan creation functions, the requested plan is said to be configured for in-place operations if identical input and output buffers are used when the plan is created. The plan is configured for out-of-place operations otherwise.

Note

• hipFFTW does not support split complex formats, real-to-real transforms, nor distributed transforms;

• hipFFTW does not support transforms of more than 3 dimensions, that is, rank > 3 is not supported;

• hipFFTW does not support transforms of more than 1 batch dimension, that is, howmany_rank > 1 is not supported.

Basic plans

Basic plans are implicitly configured for unbatched transforms with compact, default data layouts. For \(d\)-dimensional (\(d > 0\)) transforms of lengths \(n_0 \times n_1 \times \ldots \times n_{d-1}\) (\(n_{i} > 0\, \forall i \in \lbrace 0, 1, \ldots, d-1\rbrace\)), default data layouts use strides \(s_i\) along dimension \(i\) where

• \(s_{d-1} = 1\);

• if \(d > 1\),

  • \(s_{d-2} = 2 \lfloor n_{d-1} / 2 + 1 \rfloor\) on input (resp. output) and \(s_{d-2} = \lfloor n_{d-1} / 2 + 1 \rfloor\) on output (resp. input) for forward (resp. backward) real in-place transforms;

  • \(s_{d-2} = n_{d-1}\) on input (resp. output) and \(s_{d-2} = \lfloor n_{d-1} / 2 + 1 \rfloor\) on output (resp. input) for forward (resp. backward) real out-of-place transforms;

  • \(n_{d-1}\) otherwise.

• if \(d > 2\), \(s_{i} = n_{i+1}s_{i+1}\) for \(0 \leq i < d-2\).

The following functions can be used for creating basic hipFFTW plans.

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

Creates a basic plan for a one-dimensional, double-precision, complex discrete Fourier transform of length n.

Parameters:

• n – [in] strictly positive length of the transform;

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• sign – [in] exponent sign defining the desired complex transform (FFTW_FORWARD or FFTW_BACKWARD);

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

fftwf_plan fftwf_plan_dft_1d(int n, fftwf_complex *in, fftwf_complex *out, int sign, unsigned flags)

Single-precision equivalent of fftw_plan_dft_1d.

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

Creates a basic plan for a two-dimensional, double-precision, complex discrete Fourier transform of lengths n0 x n1.

Parameters:

• n0, n1 – [in] strictly positive lengths of the transform;

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• sign – [in] exponent sign defining the desired complex transform (FFTW_FORWARD or FFTW_BACKWARD);

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_dft_2d.

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

Creates a basic plan for a three-dimensional, double-precision, complex discrete Fourier transform of lengths n0 x n1 x n2.

Parameters:

• n0, n1, n2 – [in] strictly positive lengths of the transform;

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• sign – [in] exponent sign defining the desired complex transform (FFTW_FORWARD or FFTW_BACKWARD);

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_dft_3d.

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

Creates a basic plan for a multidimensional, double-precision, complex discrete Fourier transform of lengths n[0] x n[1] x ... x n[rank-1].

Parameters:

• rank – [in] strictly positive rank of the transform;

• n – [in] array of strictly positive lengths of the transform (must be of size rank);

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• sign – [in] exponent sign defining the desired complex transform (FFTW_FORWARD or FFTW_BACKWARD);

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_dft.

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

Creates a basic plan for a one-dimensional, double-precision, real forward discrete Fourier transform of length n.

Parameters:

• n – [in] strictly positive length of the transform;

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_dft_r2c_1d.

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

Creates a basic plan for a two-dimensional, double-precision, real forward discrete Fourier transform of lengths n0 x n1.

Parameters:

• n0, n1 – [in] strictly positive lengths of the transform;

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_dft_r2c_2d.

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

Creates a basic plan for a three-dimensional, double-precision, real forward discrete Fourier transform of lengths n0 x n1 x n2.

Parameters:

• n0, n1, n2 – [in] strictly positive lengths of the transform;

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_dft_r2c_3d.

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

Creates a basic plan for a multidimensional, double-precision, real forward discrete Fourier transform of lengths n[0] x n[1] x ... x n[rank-1].

Parameters:

• rank – [in] strictly positive rank of the transform;

• n – [in] array of strictly positive lengths of the transform (must be of size rank);

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_dft_r2c.

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

Creates a basic plan for a one-dimensional, double-precision, real backward (inverse) discrete Fourier transform of length n.

Parameters:

• n – [in] strictly positive length of the transform;

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_dft_c2r_1d.

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

Creates a basic plan for a two-dimensional, double-precision, real backward (inverse) discrete Fourier transform of lengths n0 x n1.

Parameters:

• n0, n1 – [in] strictly positive lengths of the transform;

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_dft_c2r_2d.

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

Creates a basic plan for a three-dimensional, double-precision, real backward (inverse) discrete Fourier transform of lengths n0 x n1 x n2.

Parameters:

• n0, n1, n2 – [in] strictly positive lengths of the transform;

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_dft_c2r_3d.

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

Creates a basic plan for a multidimensional, double-precision, real backward (inverse) discrete Fourier transform of lengths n[0] x n[1] x ... x n[rank-1].

Parameters:

• rank – [in] strictly positive rank of the transform;

• n – [in] array of strictly positive lengths of the transform (must be of size rank);

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_dft_c2r.

Advanced plans

Advanced plans support batched transforms and some non-default data layouts. The following additional arguments parameterize the input data layout for a \(d\)-dimensional transform (\(d > 0\)) of lengths n[0] x n[1] x ... x n[d-1]:

• istride is the elementary stride, that is, the stride along the last dimension;

• idist is the distance between consecutive data sequences in the batch;

• inembed is an array of \(d\) integer values representing the dimensions of a \(d\)-dimensional array embedding the input data.

ostride, odist, and onembed parameterize the output data layout of the transform similarly.

Setting inembed to NULL is equivalent to a using inembed[i] = n[i] for all \(0 \leq i < d-1\) and

• inembed[d-1] = n[d-1] for complex transforms or out-of-place real forward transforms;

• inembed[d-1] = n[d-1]/2 + 1 for backward real transforms;

• inembed[d-1] = 2 * (n[d-1]/2 + 1) for in-place forward real transforms.

The same behavior holds for setting onembed to NULL, subsituting “forward” for “backward” in the description above (and vice versa).

If set explicitly, all the inembed and onembed values must be larger than or equal to their default values.

Note

Using NULL for inembed and for onembed as well as istride = 1 and ostride = 1 results in the same data layout as for basic plan in case of unbatched transforms (howmany = 1).

Concretely, considering a batched, three-dimensional transform, the data element of logical index \(\left(j_0, j_1, j_2\right)\) in the \(k\)-th batch is in[idist * k + istride * (j_2 + inembed[2] * (j_1 + inembed[1] * j_0))] on input and out[odist * k + ostride * (j_2 + onembed[2] * (j_1 + onembed[1] * j_0))] on output.

The following functions can be used for creating advanced hipFFTW plans.

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

Creates an advanced plan for a multidimensional, double-precision, complex discrete Fourier transform of lengths n[0] x n[1] x ... x n[rank-1] and batch size howmany.

Parameters:

• rank – [in] strictly positive rank of the transform;

• n – [in] array of strictly positive lengths of the transform (must be of size rank);

• howmany – [in] strictly positive batch size;

• in – [in] pointer to the input buffer for the transform;

• inembed – [in] array of strictly positive input-embedding lengths (must be of size rank). Default input-embedding is considered if set to NULL;

• istride – [in] strictly positive elementary stride in input data (along the last dimension);

• idist – [in] strictly positive distance between consecutive input data sequences in the batch;

• out – [in] pointer to the output buffer for the transform;

• onembed – [in] array of strictly positive output-embedding lengths (must be of size rank). Default output-embedding is considered if set to NULL;

• ostride – [in] strictly positive elementary stride in output data (along the last dimension);

• odist – [in] strictly positive distance between consecutive output data sequences in the batch;

• sign – [in] exponent sign defining the desired complex transform (FFTW_FORWARD or FFTW_BACKWARD);

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_many_dft.

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

Creates an advanced plan for a multidimensional, double-precision, real forward discrete Fourier transform of lengths n[0] x n[1] x ... x n[rank-1] and batch size howmany.

Parameters:

• rank – [in] strictly positive rank of the transform;

• n – [in] array of strictly positive lengths of the transform (must be of size rank);

• howmany – [in] strictly positive batch size;

• in – [in] pointer to the input buffer for the transform;

• inembed – [in] array of strictly positive input-embedding lengths (must be of size rank). Default input-embedding is considered if set to NULL;

• istride – [in] strictly positive elementary stride in input data (along the last dimension);

• idist – [in] strictly positive distance between consecutive input data sequences in the batch;

• out – [in] pointer to the output buffer for the transform;

• onembed – [in] array of strictly positive output-embedding lengths (must be of size rank). Default output-embedding is considered if set to NULL;

• ostride – [in] strictly positive elementary stride in output data (along the last dimension);

• odist – [in] strictly positive distance between consecutive output data sequences in the batch;

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_many_dft_r2c.

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

Creates an advanced plan for a multidimensional, double-precision, real backward (inverse) discrete Fourier transform of lengths n[0] x n[1] x ... x n[rank-1] and batch size howmany.

Parameters:

• rank – [in] strictly positive rank of the transform;

• n – [in] array of strictly positive lengths of the transform (must be of size rank);

• howmany – [in] strictly positive batch size;

• in – [in] pointer to the input buffer for the transform;

• inembed – [in] array of strictly positive input-embedding lengths (must be of size rank). Default input-embedding is considered if set to NULL;

• istride – [in] strictly positive elementary stride in input data (along the last dimension);

• idist – [in] strictly positive distance between consecutive input data sequences in the batch;

• out – [in] pointer to the output buffer for the transform;

• onembed – [in] array of strictly positive output-embedding lengths (must be of size rank). Default output-embedding is considered if set to NULL;

• ostride – [in] strictly positive elementary stride in output data (along the last dimension);

• odist – [in] strictly positive distance between consecutive output data sequences in the batch;

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

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

Single-precision equivalent of fftw_plan_many_dft_c2r.

Arbitrary plans

Arbitrary plans support batched transforms with arbitrary data layouts.

Considering a \(d\)-dimensional transform (\(d > 0\)) of lengths n[0] x n[1] x ... x n[d-1] batched m[0] x m[1] x ... x m[q-1] times (\(q > 0\)), arbitrary input and output data layouts can be set via the dims and howmany_dims arguments of the plan creation functions below. Their rank and howmany_rank arguments capture the (strictly positive) values of \(d\) and \(q\), respectively.

Specifically, dims must be an array of \(d\) fftw_iodim (or fftw_iodim64) values such that, for all \(0 \leq i < d\),

• dims[i].n is equal to n[i] (must be strictly positive);

• dims[i].is is the input stride along the i-th data dimension;

• dims[i].os is the output stride along the i-th data dimension.

Similarly, howmany_dims must be an array of \(q\) fftw_iodim (or fftw_iodim64) values such that, for all \(0 \leq j < q\),

• howmany_dims[j].n is equal to m[j] (must be strictly positive);

• howmany_dims[j].is is the input distance along the j-th batch dimension;

• howmany_dims[j].os is the output distance along the j-th batch dimension.

The following functions can be used for creating arbitrary hipFFTW plans.

fftw_plan fftw_plan_guru_dft(int rank, const fftw_iodim *dims, int howmany_rank, const fftw_iodim *howmany_dims, fftw_complex *in, fftw_complex *out, int sign, unsigned flags)

Creates an arbitrary plan for a multidimensional, double-precision, complex discrete Fourier transform of lengths dims[0].n x dims[1].n x ... x dims[rank-1].n and batch sizes howmany_dims[0].n x howmany_dims[1].n x ... x howmany_dims[howmany_rank-1].n.

Parameters:

• rank – [in] strictly positive rank of the transform;

• dims – [in] array of rank fftw_iodim values;

• howmany_rank – [in] strictly positive rank of the transform’s batch sizes;

• howmany_dims – [in] array of howmany_rank fftw_iodim values;

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• sign – [in] exponent sign defining the desired complex transform (FFTW_FORWARD or FFTW_BACKWARD);

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

fftwf_plan fftwf_plan_guru_dft(int rank, const fftwf_iodim *dims, int howmany_rank, const fftwf_iodim *howmany_dims, fftwf_complex *in, fftwf_complex *out, int sign, unsigned flags)

Single-precision equivalent of fftw_plan_guru_dft.

fftw_plan fftw_plan_guru_dft_r2c(int rank, const fftw_iodim *dims, int howmany_rank, const fftw_iodim *howmany_dims, double *in, fftw_complex *out, unsigned flags)

Creates an arbitrary plan for a multidimensional, double-precision, real forward discrete Fourier transform of lengths dims[0].n x dims[1].n x ... x dims[rank-1].n and batch sizes howmany_dims[0].n x howmany_dims[1].n x ... x howmany_dims[howmany_rank-1].n.

Parameters:

• rank – [in] strictly positive rank of the transform;

• dims – [in] array of rank fftw_iodim values;

• howmany_rank – [in] strictly positive rank of the transform’s batch sizes;

• howmany_dims – [in] array of howmany_rank fftw_iodim values;

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

fftwf_plan fftwf_plan_guru_dft_r2c(int rank, const fftwf_iodim *dims, int howmany_rank, const fftwf_iodim *howmany_dims, float *in, fftwf_complex *out, unsigned flags)

Single-precision equivalent of fftw_plan_guru_dft_r2c.

fftw_plan fftw_plan_guru_dft_c2r(int rank, const fftw_iodim *dims, int howmany_rank, const fftw_iodim *howmany_dims, fftw_complex *in, double *out, unsigned flags)

Creates an arbitrary plan for a multidimensional, double-precision, real backward (inverse) discrete Fourier transform of lengths dims[0].n x dims[1].n x ... x dims[rank-1].n and batch sizes howmany_dims[0].n x howmany_dims[1].n x ... x howmany_dims[howmany_rank-1].n.

Parameters:

• rank – [in] strictly positive rank of the transform;

• dims – [in] array of rank fftw_iodim values;

• howmany_rank – [in] strictly positive rank of the transform’s batch sizes;

• howmany_dims – [in] array of howmany_rank fftw_iodim values;

• in – [in] pointer to the input buffer for the transform;

• out – [in] pointer to the output buffer for the transform;

• flags – [in] bitwise OR (|) combination of zero or more constant flag values.

Returns:

a valid double-precision hipFFTW plan ready for execution upon success (nullptr otherwise).

fftwf_plan fftwf_plan_guru_dft_c2r(int rank, const fftwf_iodim *dims, int howmany_rank, const fftwf_iodim *howmany_dims, fftwf_complex *in, float *out, unsigned flags)

Single-precision equivalent of fftw_plan_guru_dft_c2r.

fftw_plan fftw_plan_guru64_dft(int rank, const fftw_iodim64 *dims, int howmany_rank, const fftw_iodim64 *howmany_dims, fftw_complex *in, fftw_complex *out, int sign, unsigned flags)

Equivalent of fftw_plan_guru_dft using layout-describing values of type fftw_iodim64 instead of fftw_iodim.

fftwf_plan fftwf_plan_guru64_dft(int rank, const fftwf_iodim64 *dims, int howmany_rank, const fftwf_iodim64 *howmany_dims, fftwf_complex *in, fftwf_complex *out, int sign, unsigned flags)

Equivalent of fftwf_plan_guru_dft using layout-describing values of type fftwf_iodim64 instead of fftwf_iodim.

fftw_plan fftw_plan_guru64_dft_r2c(int rank, const fftw_iodim64 *dims, int howmany_rank, const fftw_iodim64 *howmany_dims, double *in, fftw_complex *out, unsigned flags)

Equivalent of fftw_plan_guru_dft_r2c using layout-describing values of type fftw_iodim64 instead of fftw_iodim.

fftwf_plan fftwf_plan_guru64_dft_r2c(int rank, const fftwf_iodim64 *dims, int howmany_rank, const fftwf_iodim64 *howmany_dims, float *in, fftwf_complex *out, unsigned flags)

Equivalent of fftwf_plan_guru_dft_r2c using layout-describing values of type fftwf_iodim64 instead of fftwf_iodim.

fftw_plan fftw_plan_guru64_dft_c2r(int rank, const fftw_iodim64 *dims, int howmany_rank, const fftw_iodim64 *howmany_dims, fftw_complex *in, double *out, unsigned flags)

Equivalent of fftw_plan_guru_dft_c2r using layout-describing values of type fftw_iodim64 instead of fftw_iodim.

fftwf_plan fftwf_plan_guru64_dft_c2r(int rank, const fftwf_iodim64 *dims, int howmany_rank, const fftwf_iodim64 *howmany_dims, fftwf_complex *in, float *out, unsigned flags)

Equivalent of fftwf_plan_guru_dft_c2r using layout-describing values of type fftwf_iodim64 instead of fftwf_iodim.

Data layout requirements for hipFFTW plans

For complex in-place transforms, hipFFTW requires all strides and distances to be equal in input and output data layouts. For real in-place transforms, hipFFTW requires:

• unit elementary strides along the \(\left(d-1\right)\)-th dimension for \(d\)-dimensional transforms;

• all other input (resp. output) strides and distances to be twice the corresponding output (resp. input) strides and distances for forward (resp. backward) transforms.

Negative strides and distances are not supported by hipFFTW.

Plan execution

After they are successfully created, hipFFTW plans can be executed, that is, used for computing the discrete Fourier transform that they capture. The generic execution functions implicitly reuse the input and output buffers that were set at plan creation. If that is not possible or impractical, new input and output buffers can be communicated instead by using the new-arrays execution functions.

Using buffers set at plan creation for computation

void fftw_execute(const fftw_plan plan)

Computes the discrete Fourier transform that a double-precision plan captures using the input and output data buffers that were communicated at plan’s creation.

Parameters:

plan – [in] the double-precision plan capturing the transform to compute.

void fftwf_execute(const fftwf_plan plan)

Single-precision equivalent of fftw_execute.

Using new buffers for computation

void fftw_execute_dft(const fftw_plan plan, fftw_complex *in, fftw_complex *out)

Computes the discrete Fourier transform that a double-precision plan captures using new input and output data buffers. The plan must have been created for a complex transform.

Parameters:

• plan – [in] the double-precision plan capturing the complex transform to compute;

• in – [in] pointer to a new input buffer for the transform;

• out – [out] pointer to a new output buffer for the transform.

void fftwf_execute_dft(const fftwf_plan plan, fftwf_complex *in, fftwf_complex *out)

Single-precision equivalent of fftw_execute_dft.

void fftw_execute_dft_r2c(const fftw_plan plan, double *in, fftw_complex *out)

Computes the discrete Fourier transform that a double-precision plan captures using new input and output data buffers. The plan must have been created for a real forward transform.

Parameters:

• plan – [in] the double-precision plan capturing the real forward transform to compute;

• in – [in] pointer to a new input buffer for the transform;

• out – [out] pointer to a new output buffer for the transform.

void fftwf_execute_dft_r2c(const fftwf_plan plan, float *in, fftwf_complex *out)

Single-precision equivalent of fftw_execute_dft_r2c.

void fftw_execute_dft_c2r(const fftw_plan plan, fftw_complex *in, double *out)

Computes the discrete Fourier transform that a double-precision plan captures using new input and output data buffers. The plan must have been created for a real backward (inverse) transform.

Parameters:

• plan – [in] the double-precision plan capturing the real backward (inverse) transform to compute;

• in – [in] pointer to a new input buffer for the transform;

• out – [out] pointer to a new output buffer for the transform.

void fftwf_execute_dft_c2r(const fftwf_plan plan, fftwf_complex *in, float *out)

Single-precision equivalent of fftw_execute_dft_c2r.

Note

When new input and output buffers are used for execution, they must honor the placement that was set at plan creation. In other words, the result of (void*)in == (void*)out must be unchanged between plan creation and plan execution.

Note

If the type of memory for the output buffer is directly accessible by the host, hipFFTW enforces synchronization before returning from any of the above execution functions to guarantee that the results are readily available to the host upon completion of the execution function.

Plan destruction

When no longer needed or going out of scope, hipFFTW plans must be destructed using either of the following functions matching the plan’s precision.

void fftw_destroy_plan(fftw_plan plan)

Deallocates a double-precision plan and frees all its resources.

Parameters:

plan – [in] plan to be destroyed.

void fftwf_destroy_plan(fftwf_plan plan)

Single-precision equivalent of fftw_destroy_plan.

Other utility functions (existing yet non-functional)

The following functions exist in hipFFTW but are not functional in any way. They effectively ignore all arguments and systematically return 0.0 when a double value needs to be returned.

• fftw_print_plan and fftwf_print_plan;

• fftw_set_timelimit and fftwf_set_timelimit;

• fftw_cost and fftwf_cost;

• fftw_flops and fftwf_flops;

• fftw_cleanup and fftwf_cleanup.

Environment variables specific to hipFFTW

Enforcing size limits on types of memory for user-managed buffers

By setting any of the environment variables

• HIPFFTW_BYTE_SIZE_LIMIT_PINNED_HOST_ALLOC;

• HIPFFTW_BYTE_SIZE_LIMIT_PAGEABLE_HOST_ALLOC;

to a non-negative integer value, users can instruct hipFFTW to observe the value set for the maximal byte size that can be considered for the corresponding kind of host-accessible memory for any individual allocation requested via the buffer allocation functions. Setting any of the above variables to 0 effectively prevents the corresponding kind of memory to be considered in user-requested buffer allocations altogether.

Making hipFFTW verbose

Debugging failures or errors suspected to be triggered by hipFFTW can be challenging, particularly if the root cause lies in any of the execution functions, given that these functions’ signatures make such errors silent by design. Setting the environment variable HIPFFTW_LOG_EXCEPTIONS to a strictly positive integer value effectively instructs hipFFTW to become verbose about internal exceptions it might encounter by reporting them to the standard error stream.

Note

The hipFFTW interface is C-compatible, even when HIPFFTW_LOG_EXCEPTIONS is set as described above.