API Usage¶

This section describes usage of the hipFFT library API. The hipFFT API follows the cuFFT API.

Types¶

There are a few data structures that are internal to the library. The pointer types to these structures are given below. The user would need to use these types to create handles and pass them between different library functions.

HIPFFT_FORWARD¶: Perform a forward FFT.

HIPFFT_BACKWARD¶: Perform a backward/inverse FFT.

enum hipfftType¶

Transform type.

This type is used to declare the Fourier transform type that will be executed.

Values:

enumerator HIPFFT_R2C¶: Real to complex (interleaved)

enumerator HIPFFT_C2R¶: Complex (interleaved) to real

enumerator HIPFFT_C2C¶: Complex to complex (interleaved)

enumerator HIPFFT_D2Z¶: Double to double-complex (interleaved)

enumerator HIPFFT_Z2D¶: Double-complex (interleaved) to double

enumerator HIPFFT_Z2Z¶: Double-complex to double-complex (interleaved)

typedef struct hipfftHandle_t *hipfftHandle¶

enum hipfftResult¶

Result/status/error codes.

Values:

enumerator HIPFFT_SUCCESS¶: hipFFT operation was successful

enumerator HIPFFT_INVALID_PLAN¶: hipFFT was passed an invalid plan handle

enumerator HIPFFT_ALLOC_FAILED¶: hipFFT failed to allocate GPU or CPU memory

enumerator HIPFFT_INVALID_TYPE¶: No longer used

enumerator HIPFFT_INVALID_VALUE¶: User specified an invalid pointer or parameter

enumerator HIPFFT_INTERNAL_ERROR¶: Driver or internal hipFFT library error

enumerator HIPFFT_EXEC_FAILED¶: Failed to execute an FFT on the GPU

enumerator HIPFFT_SETUP_FAILED¶: hipFFT failed to initialize

enumerator HIPFFT_INVALID_SIZE¶: User specified an invalid transform size

enumerator HIPFFT_UNALIGNED_DATA¶: No longer used

enumerator HIPFFT_INCOMPLETE_PARAMETER_LIST¶: Missing parameters in call

enumerator HIPFFT_INVALID_DEVICE¶: Execution of a plan was on different GPU than plan creation

enumerator HIPFFT_PARSE_ERROR¶: Internal plan database error

enumerator HIPFFT_NO_WORKSPACE¶: No workspace has been provided prior to plan execution

enumerator HIPFFT_NOT_IMPLEMENTED¶: Function does not implement functionality for parameters given.

enumerator HIPFFT_NOT_SUPPORTED¶: Operation is not supported for parameters given.

Simple plans¶

These planning routines allocate a plan for you. If execution of the plan requires a work buffer, it will be created (and destroyed) automatically.

hipfftResult hipfftPlan1d(hipfftHandle *plan, int nx, hipfftType type, int batch)¶

Create a new one-dimensional FFT plan.

Allocate and initialize a new one-dimensional FFT plan.

Parameters:

plan – [out] Pointer to the FFT plan handle.
nx – [in] FFT length.
type – [in] FFT type.
batch – [in] Number of batched transforms to compute.

hipfftResult hipfftPlan2d(hipfftHandle *plan, int nx, int ny, hipfftType type)¶

Create a new two-dimensional FFT plan.

Allocate and initialize a new two-dimensional FFT plan. Two-dimensional data should be stored in C ordering (row-major format), so that indexes in y-direction (j index) vary the fastest.

Parameters:

plan – [out] Pointer to the FFT plan handle.
nx – [in] Number of elements in the x-direction (slow index).
ny – [in] Number of elements in the y-direction (fast index).
type – [in] FFT type.

hipfftResult hipfftPlan3d(hipfftHandle *plan, int nx, int ny, int nz, hipfftType type)¶

Create a new three-dimensional FFT plan.

Allocate and initialize a new three-dimensional FFT plan. Three-dimensional data should be stored in C ordering (row-major format), so that indexes in z-direction (k index) vary the fastest.

Parameters:

plan – [out] Pointer to the FFT plan handle.
nx – [in] Number of elements in the x-direction (slowest index).
ny – [in] Number of elements in the y-direction.
nz – [in] Number of elements in the z-direction (fastest index).
type – [in] FFT type.

User managed simple plans¶

These planning routines assume that you have allocated a plan (hipfftHandle) yourself; and that you will manage a work area as well.

If you want to manage your own work buffer… XXX

hipfftResult hipfftCreate(hipfftHandle *plan)¶: Allocate a new plan.

hipfftResult hipfftDestroy(hipfftHandle plan)¶: Destroy and deallocate an existing plan.

hipfftResult hipfftSetAutoAllocation(hipfftHandle plan, int autoAllocate)¶

Set the plan’s auto-allocation flag. The plan will allocate its own workarea.

Parameters:

plan – [in] Pointer to the FFT plan.
autoAllocate – [in] 0 to disable auto-allocation, non-zero to enable.

hipfftResult hipfftMakePlan1d(hipfftHandle plan, int nx, hipfftType type, int batch, size_t *workSize)¶

Initialize a new one-dimensional FFT plan.

Assumes that the plan has been created already, and modifies the plan associated with the plan handle.

Parameters:

plan – [in] Handle of the FFT plan.
nx – [in] FFT length.
type – [in] FFT type.
batch – [in] Number of batched transforms to compute.

hipfftResult hipfftMakePlan2d(hipfftHandle plan, int nx, int ny, hipfftType type, size_t *workSize)¶

Initialize a new two-dimensional FFT plan.

Assumes that the plan has been created already, and modifies the plan associated with the plan handle. Two-dimensional data should be stored in C ordering (row-major format), so that indexes in y-direction (j index) vary the fastest.

Parameters:

plan – [in] Handle of the FFT plan.
nx – [in] Number of elements in the x-direction (slow index).
ny – [in] Number of elements in the y-direction (fast index).
type – [in] FFT type.
workSize – [out] Pointer to work area size (returned value).

hipfftResult hipfftMakePlan3d(hipfftHandle plan, int nx, int ny, int nz, hipfftType type, size_t *workSize)¶

Initialize a new two-dimensional FFT plan.

Assumes that the plan has been created already, and modifies the plan associated with the plan handle. Three-dimensional data should be stored in C ordering (row-major format), so that indexes in z-direction (k index) vary the fastest.

Parameters:

plan – [in] Handle of the FFT plan.
nx – [in] Number of elements in the x-direction (slowest index).
ny – [in] Number of elements in the y-direction.
nz – [in] Number of elements in the z-direction (fastest index).
type – [in] FFT type.
workSize – [out] Pointer to work area size (returned value).

More advanced plans¶

hipfftResult hipfftMakePlanMany(hipfftHandle plan, int rank, int *n, int *inembed, int istride, int idist, int *onembed, int ostride, int odist, hipfftType type, int batch, size_t *workSize)¶

Initialize a new batched rank-dimensional FFT plan with advanced data layout.

Assumes that the plan has been created already, and modifies the plan associated with the plan handle. The number of elements to transform in each direction of the input data in the FFT plan is specified in n.

The batch parameter tells hipFFT how many transforms to perform. The distance between the first elements of two consecutive batches of the input and output data are specified with the idist and odist parameters.

The inembed and onembed parameters define the input and output data layouts. The number of elements in the data is assumed to be larger than the number of elements in the transform. Strided data layouts are also supported. Strides along the fastest direction in the input and output data are specified via the istride and ostride parameters.

If both inembed and onembed parameters are set to NULL, all the advanced data layout parameters are ignored and reverted to default values, i.e., the batched transform is performed with non-strided data access and the number of data/transform elements are assumed to be

equivalent.

Parameters:

plan – [out] Pointer to the FFT plan handle.
rank – [in] Dimension of transform (1, 2, or 3).
n – [in] Number of elements to transform in the x/y/z directions.
inembed – [in] Number of elements in the input data in the x/y/z directions.
istride – [in] Distance between two successive elements in the input data.
idist – [in] Distance between input batches.
onembed – [in] Number of elements in the output data in the x/y/z directions.
ostride – [in] Distance between two successive elements in the output data.
odist – [in] Distance between output batches.
type – [in] FFT type.
batch – [in] Number of batched transforms to perform.
workSize – [out] Pointer to work area size (returned value).

Estimating work area sizes¶

These call return estimates of the work area required to support a plan generated with the same parameters (either with the simple or extensible API). Callers who choose to manage work area allocation within their application must use this call after plan generation, and after any hipfftSet*() calls subsequent to plan generation, if those calls might alter the required work space size.

hipfftResult hipfftEstimate1d(int nx, hipfftType type, int batch, size_t *workSize)¶

Return an estimate of the work area size required for a 1D plan.

Parameters:

nx – [in] Number of elements in the x-direction.
type – [in] FFT type.
workSize – [out] Pointer to work area size (returned value).

hipfftResult hipfftEstimate2d(int nx, int ny, hipfftType type, size_t *workSize)¶

Return an estimate of the work area size required for a 2D plan.

Parameters:

nx – [in] Number of elements in the x-direction.
ny – [in] Number of elements in the y-direction.
type – [in] FFT type.
workSize – [out] Pointer to work area size (returned value).

hipfftResult hipfftEstimate3d(int nx, int ny, int nz, hipfftType type, size_t *workSize)¶

Return an estimate of the work area size required for a 3D plan.

Parameters:

nx – [in] Number of elements in the x-direction.
ny – [in] Number of elements in the y-direction.
nz – [in] Number of elements in the z-direction.
type – [in] FFT type.
workSize – [out] Pointer to work area size (returned value).

hipfftResult hipfftEstimateMany(int rank, int *n, int *inembed, int istride, int idist, int *onembed, int ostride, int odist, hipfftType type, int batch, size_t *workSize)¶

Return an estimate of the work area size required for a rank-dimensional plan.

Parameters:

rank – [in] Dimension of FFT transform (1, 2, or 3).
n – [in] Number of elements in the x/y/z directions.
inembed – [in]
istride – [in]
idist – [in] Distance between input batches.
onembed – [in]
ostride – [in]
odist – [in] Distance between output batches.
type – [in] FFT type.
batch – [in] Number of batched transforms to perform.
workSize – [out] Pointer to work area size (returned value).

Accurate work area sizes¶

After plan generation is complete, an accurate work area size can be obtained with these routines.

hipfftResult hipfftGetSize1d(hipfftHandle plan, int nx, hipfftType type, int batch, size_t *workSize)¶

Return size of the work area size required for a 1D plan.

Parameters:

plan – [in] Pointer to the FFT plan.
nx – [in] Number of elements in the x-direction.
type – [in] FFT type.
workSize – [out] Pointer to work area size (returned value).

hipfftResult hipfftGetSize2d(hipfftHandle plan, int nx, int ny, hipfftType type, size_t *workSize)¶

Return size of the work area size required for a 2D plan.

Parameters:

plan – [in] Pointer to the FFT plan.
nx – [in] Number of elements in the x-direction.
ny – [in] Number of elements in the y-direction.
type – [in] FFT type.
workSize – [out] Pointer to work area size (returned value).

hipfftResult hipfftGetSize3d(hipfftHandle plan, int nx, int ny, int nz, hipfftType type, size_t *workSize)¶

Return size of the work area size required for a 3D plan.

Parameters:

plan – [in] Pointer to the FFT plan.
nx – [in] Number of elements in the x-direction.
ny – [in] Number of elements in the y-direction.
nz – [in] Number of elements in the z-direction.
type – [in] FFT type.
workSize – [out] Pointer to work area size (returned value).

hipfftResult hipfftGetSizeMany(hipfftHandle plan, int rank, int *n, int *inembed, int istride, int idist, int *onembed, int ostride, int odist, hipfftType type, int batch, size_t *workSize)¶

Return size of the work area size required for a rank-dimensional plan.

Parameters:

plan – [in] Pointer to the FFT plan.
rank – [in] Dimension of FFT transform (1, 2, or 3).
n – [in] Number of elements in the x/y/z directions.
inembed – [in]
istride – [in]
idist – [in] Distance between input batches.
onembed – [in]
ostride – [in]
odist – [in] Distance between output batches.
type – [in] FFT type.
batch – [in] Number of batched transforms to perform.
workSize – [out] Pointer to work area size (returned value).

Executing plans¶

Once you have created an FFT plan, you can execute it using one of the hipfftExec* functions.

For real-to-complex transforms, the output buffer XXX

For complex-to-real transforms, the output buffer XXX

hipfftResult hipfftExecC2C(hipfftHandle plan, hipfftComplex *idata, hipfftComplex *odata, int direction)¶

Execute a (float) complex-to-complex FFT.