Skip to main content
`Ctrl`+`K`

# 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:

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, `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.