hipFFTW API usage

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;.

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:

pinned host memory (first);
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, batch_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#

Arbitrary plans#

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.

hipFFTW API usage

Contents

hipFFTW API usage#

Data types#

Constant values#

Flag values#

Sign values#

Buffer management#

Plan creation#

Basic plans#

Advanced plans#

Arbitrary plans#

Plan execution#

Using buffers set at plan creation for computation#

Using new buffers for computation#

Plan destruction#

Other utility functions (existing yet non-functional)#

Environment variables specific to hipFFTW#

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

Making hipFFTW verbose#