rocFFT

https://rocm.docs.amd.com/projects/rocFFT/en/latest/
Admin
The rocFFT library implements the discrete Fast Fourier Transform (FFT) in HIP for GPU devices,...
Tokens:27,316
Snippets:320
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Client Dependencies on Ubuntu

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/install/building-installing-rocfft.html

Install the necessary dependencies for building rocFFT clients on Ubuntu systems using the apt package manager.

```bash
sudo apt install libgtest-dev libfftw3-dev

```

--------------------------------

### Build rocFFT Documentation Locally

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Navigate to the documentation directory, install dependencies, and run the Sphinx build command to generate HTML documentation.

```bash
cd projects/rocfft/docs

pip3 install -r sphinx/requirements.txt

python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
```

--------------------------------

### Library Setup

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Initializes the rocFFT library. This function should be called once before any other library functions are used.

```c
rocfft_status rocfft_setup()
```

--------------------------------

### Install Client Dependencies on Red Hat

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/install/building-installing-rocfft.html

For Red Hat-related distributions, install the client dependencies using the package manager. The package names differ from Ubuntu.

```bash
sudo yum install gtest-devel fftw-devel

```

--------------------------------

### Basic rocFFT Computation Example

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/how-to/working-with-rocfft.html

This example demonstrates the fundamental steps of using rocFFT for a complex forward transform. It covers initialization, data transfer to the GPU, plan creation, execution with optional work buffer management, and cleanup.

```c++
#include <iostream>
#include <vector>
#include "hip/hip_runtime_api.h"
#include "hip/hip_vector_types.h"
#include "rocfft/rocfft.h"

int main()
{
        // rocFFT gpu compute
        // ========================================

        rocfft_setup();

        size_t N = 16;
        size_t Nbytes = N * sizeof(float2);

        // Create HIP device buffer
        float2 *x;
        hipMalloc(&x, Nbytes);

        // Initialize data
        std::vector<float2> cx(N);
        for (size_t i = 0; i < N; i++)
        {
                cx[i].x = 1;
                cx[i].y = -1;
        }

        //  Copy data to device
        hipMemcpy(x, cx.data(), Nbytes, hipMemcpyHostToDevice);

        // Create rocFFT plan
        rocfft_plan plan = nullptr;
        size_t length = N;
        rocfft_plan_create(&plan, rocfft_placement_inplace, 
             rocfft_transform_type_complex_forward, rocfft_precision_single, 
             1, &length, 1, nullptr);

        // Check if the plan requires a work buffer
        size_t work_buf_size = 0;
        // This is a single-device plan that uses the current HIP device,
        // so any work buffer would be on that device.
        rocfft_plan_get_work_buffer_size(plan, &work_buf_size);
        void* work_buf = nullptr;
        rocfft_execution_info info = nullptr;
        if(work_buf_size)
        {
                rocfft_execution_info_create(&info);
                hipMalloc(&work_buf, work_buf_size);
                rocfft_execution_info_set_work_buffer(info, work_buf, work_buf_size);
        }

        // Execute plan
        rocfft_execute(plan, (void**) &x, nullptr, info);

        // Wait for execution to finish
        hipDeviceSynchronize();

        // Clean up work buffer
        if(work_buf_size)
        {
                hipFree(work_buf);
                rocfft_execution_info_destroy(info);
        }

        // Destroy plan
        rocfft_plan_destroy(plan);

        // Copy result back to host
        std::vector<float2> y(N);
        hipMemcpy(y.data(), x, Nbytes, hipMemcpyDeviceToHost);

        // Print results
        for (size_t i = 0; i < N; i++)
        {
                std::cout << y[i].x << ", " << y[i].y << std::endl;
        }

        // Free device buffer
        hipFree(x);

        rocfft_cleanup();

        return 0;
}

```

--------------------------------

### Build rocFFT Clients from Source

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/install/building-installing-rocfft.html

Compile all client utilities (rocfft-bench, rocfft-test, samples) by enabling the `-DBUILD_CLIENTS=on` option. This process will download and build GoogleTest and FFTW if they are not already installed. rocFFT uses version 1.11 of GoogleTest.

```bash
mkdir build && cd build
cmake -DCMAKE_CXX_COMPILER=amdclang++ -DCMAKE_C_COMPILER=amdclang -DBUILD_CLIENTS=on ..
make -j

```

--------------------------------

### Library Setup and Cleanup

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Functions for initializing and cleaning up the rocFFT library. These should be called once at the beginning and end of the application's use of rocFFT.

```APIDOC
## rocfft_setup()

### Description
Initializes the rocFFT library. This function must be called before any other rocFFT functions.

### Method
rocfft_setup

### Parameters
None

## rocfft_cleanup()

### Description
Cleans up the rocFFT library. This function should be called after all rocFFT operations are complete.

### Method
rocfft_cleanup

### Parameters
None
```

--------------------------------

### Install ROCm FFT Development Package (RHEL-based)

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/install/install.html

Use this command to install the latest FFT development package for RHEL-based distributions.

```bash
sudo dnf install amdrocm-fft-devel
```

--------------------------------

### Install ROCm FFT Development Package (Debian-based)

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/install/install.html

Use this command to install the latest FFT development package for Debian-based distributions like Ubuntu.

```bash
sudo apt install amdrocm-fft-dev
```

--------------------------------

### Install ROCm FFT Development Package (SLES)

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/install/install.html

Use this command to install the latest FFT development package for SLES.

```bash
sudo zypper install amdrocm-fft-devel
```

--------------------------------

### Set Load Callback for Plan Execution

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Specifies a user-defined callback function to load input from global memory at the start of the transform. Callbacks are experimental and require at least one brick in the input field. Currently, shared_mem_bytes must be 0.

```c
rocfft_status rocfft_execution_info_set_load_callback(rocfft_execution_info info, void **cb_functions, void **cb_data, size_t shared_mem_bytes);
```

```c
Tdata load_cb(Tdata* data, size_t offset, void* cbdata, void* sharedMem);
```

--------------------------------

### rocfft_execution_info_set_load_callback

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Sets a user-defined callback function to load input from global memory at the start of the transform. This is an experimental feature. Callbacks require at least one brick on the current device and all functions in the array must perform the same logical operation.

```APIDOC
## rocfft_execution_info_set_load_callback

### Description
Sets a user-defined callback function to load input from global memory at the start of the transform. This is an experimental feature. Callbacks require at least one brick on the current device and all functions in the array must perform the same logical operation. A null value for 'cb_functions' clears any previously registered load callback.

### Method
Not specified (likely a C function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **info** (rocfft_execution_info) - Required - execution info handle
- **cb_functions** (void**) - Required - callback function pointers
- **cb_data** (void**) - Optional - callback function data, passed to the function pointer when it is called
- **shared_mem_bytes** (size_t) - Required - amount of shared memory to allocate for the callback function to use (must be 0 currently)
```

--------------------------------

### rocfft_setup

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Initializes the rocFFT library. This function must be called before any other rocFFT functions.

```APIDOC
## rocfft_setup

### Description
Initializes the rocFFT library. This function must be called before any other rocFFT functions.

### Function Signature
```c
rocfft_status rocfft_setup();
```

### Returns
- `rocfft_status_success` on success.
- `rocfft_status_failure` if initialization fails.
```

--------------------------------

### Build All Clients with Existing rocFFT Library

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Compile all rocFFT clients (bench, test, samples) from the clients directory using an existing rocFFT library. This requires specifying the path to the rocFFT library using -DCMAKE_PREFIX_PATH.

```bash
mkdir build && cd build
cmake -DCMAKE_CXX_COMPILER=amdclang++ -DCMAKE_PREFIX_PATH=/path/to/rocFFT-lib ..
make -j
```

--------------------------------

### rocfft_setup

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Initializes the rocFFT library. This function should be called once before any other library functions are used.

```APIDOC
## rocfft_setup

### Description
Library setup function, called once in program before start of library use.

### Returns
rocfft_status - Status code indicating success or failure.
```

--------------------------------

### Get Work Buffer Size

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Retrieves the required work buffer size in bytes for a given FFT plan on the current HIP device. This is crucial for allocating necessary memory for transform operations.

```c
rocfft_status rocfft_plan_get_work_buffer_size(const rocfft_plan plan, size_t *size_in_bytes)
```

--------------------------------

### rocfft_plan_description_create

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Creates a rocFFT plan description object.

```APIDOC
## rocfft_plan_description_create

### Description
Creates a rocFFT plan description object.

### Function Signature
```c
rocfft_status rocfft_plan_description_create(rocfft_plan_description* desc);
```

### Parameters
- **desc** (rocfft_plan_description*): Pointer to a `rocfft_plan_description` object to be created.

### Returns
- `rocfft_status_success` on success.
- `rocfft_status_failure` if creation fails.
```

--------------------------------

### Build rocFFT Clients Separately

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/install/building-installing-rocfft.html

To build the clients separately from the main library, navigate to the `clients` directory and invoke CMake, specifying the path to the existing rocFFT library using `-DCMAKE_PREFIX_PATH`.

```bash
mkdir build && cd build
cmake -DCMAKE_CXX_COMPILER=amdclang++ -DCMAKE_PREFIX_PATH=/path/to/rocFFT-lib ..
make -j

```

--------------------------------

### Create an FFT Plan

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Creates an FFT plan for subsequent execution. This function defines fundamental transform parameters like data placement, type, precision, dimensions, lengths, and batch size. A NULL description handle can be used for simple transforms.

```c
rocfft_status rocfft_plan_create(rocfft_plan *plan, rocfft_result_placement placement, rocfft_transform_type transform_type, rocfft_precision precision, size_t dimensions, const size_t *lengths, size_t number_of_transforms, const rocfft_plan_description description)
```

--------------------------------

### rocfft_plan_description_create

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Creates a plan description object, which is used to define the parameters of an FFT.

```APIDOC
## rocfft_plan_description_create

### Description
Creates a plan description object, which is used to define the parameters of an FFT.

### Method
`rocfft_plan_description_create(rocfft_plan_description *desc)`

### Parameters
*   **desc** (rocfft_plan_description *) - Output parameter to store the created plan description.

### Response
#### Success Response
`rocfft_status_success` on successful creation of the plan description.

#### Response Example
`rocfft_status_success`
```

--------------------------------

### Create rocFFT Plan Description

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Use this function to create a plan description object. This object is used to set advanced plan properties before creating the actual plan. Remember to free the description object after use.

```c
rocfft_status rocfft_plan_description_create(rocfft_plan_description *description)
```

--------------------------------

### Create Execution Info Handle

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Creates an execution info handle used to control plan execution and specify work buffers. This handle must be freed using rocfft_execution_info_destroy.

```c
rocfft_status rocfft_execution_info_create(rocfft_execution_info *info)
```

--------------------------------

### rocfft_plan_get_print

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Prints all plan information to stdout for debugging purposes.

```APIDOC
## rocfft_plan_get_print

### Description
Print all plan information. Prints plan details to stdout, to aid debugging

### Parameters

**plan** – **[in]** plan handle
```

--------------------------------

### Build rocFFT Shared Library with CMake

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/install/building-installing-rocfft.html

Use these commands to build a shared library for supported AMD GPUs. Ensure you are in the `rocm-libraries/projects/rocfft` directory.

```bash
mkdir build && cd build
cmake -DCMAKE_CXX_COMPILER=amdclang++ -DCMAKE_C_COMPILER=amdclang ..
make -j

```

--------------------------------

### Print Plan Information

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Prints all details of an FFT plan to standard output. This function is useful for debugging purposes.

```c
rocfft_status rocfft_plan_get_print(const rocfft_plan plan)
```

--------------------------------

### Build rocFFT Static Library with CMake

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/install/building-installing-rocfft.html

To compile a static library instead of a shared one, use the `-DBUILD_SHARED_LIBS=off` option with CMake.

```bash
mkdir build && cd build
cmake -DCMAKE_CXX_COMPILER=amdclang++ -DCMAKE_C_COMPILER=amdclang -DBUILD_SHARED_LIBS=off ..
make -j

```

--------------------------------

### rocfft_plan_create

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Creates a rocFFT plan for a given transform description. The plan is used to execute FFT transforms.

```APIDOC
## rocfft_plan_create

### Description
Creates a rocFFT plan for a given transform description. The plan is used to execute FFT transforms.

### Function Signature
```c
rocfft_status rocfft_plan_create(rocfft_plan* plan, const rocfft_plan_description desc);
```

### Parameters
- **plan** (rocfft_plan*): Pointer to a `rocfft_plan` object to be created.
- **desc** (const rocfft_plan_description): Pointer to a `rocfft_plan_description` object describing the transform.

### Returns
- `rocfft_status_success` on success.
- `rocfft_status_failure` if plan creation fails.
```

--------------------------------

### rocfft_execution_info_create

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Creates an execution info handle that can be used to control the execution of an FFT plan, including specifying work buffers and compute streams.

```APIDOC
## rocfft_execution_info_create

### Description
Creates an execution info object that allows users to control plan execution parameters like work buffers and compute streams. This object must be freed using `rocfft_execution_info_destroy`.

### Method
rocfft_execution_info_create

### Parameters
#### Output Parameters
- **info** (rocfft_execution_info *) - Pointer to the execution info handle to be created.
```

--------------------------------

### Plan Management

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Functions for creating, destroying, and querying FFT plans. A plan encapsulates the parameters and configuration for a specific FFT transform.

```APIDOC
## rocfft_plan_create()

### Description
Creates an FFT plan based on the provided description. The plan can then be used to execute FFT transforms.

### Method
rocfft_plan_create

### Parameters
* **plan** (rocfft_plan*) - Output parameter to store the created plan handle.
* **desc** (const rocfft_plan_description*) - Input parameter describing the FFT transform.

### Response
* **rocfft_status** - Status code indicating success or failure.

## rocfft_plan_destroy()

### Description
Destroys a previously created FFT plan, releasing all associated resources.

### Method
rocfft_plan_destroy

### Parameters
* **plan** (rocfft_plan) - The plan handle to destroy.

### Response
* **rocfft_status** - Status code indicating success or failure.

## rocfft_plan_get_work_buffer_size()

### Description
Retrieves the required size for a work buffer for a given FFT plan.

### Method
rocfft_plan_get_work_buffer_size

### Parameters
* **plan** (rocfft_plan) - The plan handle.
* **size_in_bytes** (size_t*) - Output parameter to store the required buffer size in bytes.

### Response
* **rocfft_status** - Status code indicating success or failure.

## rocfft_plan_get_print()

### Description
Retrieves a function pointer to a print function associated with the plan, used for debugging or introspection.

### Method
rocfft_plan_get_print

### Parameters
* **plan** (rocfft_plan) - The plan handle.
* **print_function** (void (**)(const char*)) - Output parameter to store the function pointer.

### Response
* **rocfft_status** - Status code indicating success or failure.
```

--------------------------------

### Plan Description Management

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Functions for creating, destroying, and configuring the details of an FFT plan description.

```APIDOC
## rocfft_plan_description_create()

### Description
Creates a new plan description object. This object will be used to configure the parameters for an FFT plan.

### Method
rocfft_plan_description_create

### Parameters
* **desc** (rocfft_plan_description**) - Output parameter to store the created plan description handle.

### Response
* **rocfft_status** - Status code indicating success or failure.

## rocfft_plan_description_destroy()

### Description
Destroys a previously created plan description object, releasing its resources.

### Method
rocfft_plan_description_destroy

### Parameters
* **desc** (rocfft_plan_description) - The plan description handle to destroy.

### Response
* **rocfft_status** - Status code indicating success or failure.

## rocfft_plan_description_set_scale_factor()

### Description
Sets the scale factor to be applied during the FFT transform.

### Method
rocfft_plan_description_set_scale_factor

### Parameters
* **desc** (rocfft_plan_description) - The plan description handle.
* **scale_factor** (double) - The scale factor value.

### Response
* **rocfft_status** - Status code indicating success or failure.

## rocfft_plan_description_set_data_layout()

### Description
Sets the data layout for the FFT transform, specifying how the complex numbers are arranged and the strides between elements.

### Method
rocfft_plan_description_set_data_layout

### Parameters
* **desc** (rocfft_plan_description) - The plan description handle.
* **array_type** (rocfft_array_type) - The type of array (e.g., interleaved, planar).
* **precision** (rocfft_precision) - The precision of the data (e.g., single, double).
* **dims** (const rocfft_int*) - Array of dimensions for the transform.
* **strides** (const rocfft_int*) - Array of strides between elements in each dimension.
* **distance** (rocfft_int) - The distance between consecutive transforms in a batch.

### Response
* **rocfft_status** - Status code indicating success or failure.
```

--------------------------------

### rocfft_plan_create

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Creates a plan for executing FFTs. This function configures the FFT transform based on provided parameters like dimensions, lengths, and transform type.

```APIDOC
## rocfft_plan_create

### Description
Create an FFT plan. This API creates a plan, which the user can execute subsequently. This function takes many of the fundamental parameters needed to specify a transform.

The dimensions parameter can take a value of 1, 2, or 3. The ‘lengths’ array specifies the size of data in each dimension. Note that lengths[0] is the size of the innermost dimension, lengths[1] is the next higher dimension and so on (column-major ordering).
The ‘number_of_transforms’ parameter specifies how many transforms (of the same kind) needs to be computed. By specifying a value greater than 1, a batch of transforms can be computed with a single API call.
Additionally, a handle to a plan description can be passed for more detailed transforms. For simple transforms, this parameter can be set to NULL.
The plan must be destroyed with a call to rocfft_plan_destroy.

### Parameters

#### Path Parameters
* **plan** (rocfft_plan *) - [out] plan handle
* **placement** (rocfft_result_placement) - [in] placement of result
* **transform_type** (rocfft_transform_type) - [in] type of transform
* **precision** (rocfft_precision) - [in] precision
* **dimensions** (size_t) - [in] dimensions
* **lengths** (const size_t *) - [in] dimensions-sized array of transform lengths
* **number_of_transforms** (size_t) - [in] number of transforms
* **description** (const rocfft_plan_description) - [in] description handle created by rocfft_plan_description_create; can be NULL for simple transforms

### Returns
rocfft_status - Status code indicating success or failure.
```

--------------------------------

### rocfft_plan_description_create

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Creates a plan description object that can be used to set advanced plan properties before creating a transform plan. The created description must be destroyed using `rocfft_plan_description_destroy`.

```APIDOC
## rocfft_plan_description_create

### Description
Create plan description. This API creates a plan description with which the user can set extra plan properties. The plan description must be freed with a call to rocfft_plan_description_destroy.

### Parameters

#### Parameters
- **description** (rocfft_plan_description *) - out - plan description handle
```

--------------------------------

### Set rocFFT Plan Description Data Layout

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Configures advanced input and output buffer layouts for a plan description. This includes specifying array types (real, hermitian, complex), offsets, strides, and distances between batches. Note that non-zero offsets are not currently supported.

```c
rocfft_status rocfft_plan_description_set_data_layout(rocfft_plan_description description, const rocfft_array_type in_array_type, const rocfft_array_type out_array_type, const size_t *in_offsets, const size_t *out_offsets, const size_t in_strides_size, const size_t *in_strides, const size_t in_distance, const size_t out_strides_size, const size_t *out_strides, const size_t out_distance)
```

--------------------------------

### Set Store Callback for Plan Execution

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Specifies a user-defined callback function to store output to global memory at the end of the transform. Callbacks are experimental and require at least one brick in the output field. Currently, shared_mem_bytes must be 0.

```c
rocfft_status rocfft_execution_info_set_store_callback(rocfft_execution_info info, void **cb_functions, void **cb_data, size_t shared_mem_bytes);
```

```c
void store_cb(Tdata* data, size_t offset, Tdata element, void* cbdata, void* sharedMem);
```

--------------------------------

### Execute an FFT Plan

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Executes a pre-defined FFT plan on input and output buffers. Handles both in-place and out-of-place transforms. The execution info parameter is optional for controlling streams and work buffers.

```c
rocfft_status rocfft_execute(const rocfft_plan plan, void *in_buffer[], void *out_buffer[], rocfft_execution_info info)
```

--------------------------------

### rocfft_plan_description_set_data_layout

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Specifies advanced layout parameters for input and output buffers within a plan description, including array types, offsets, strides, and distances between batches. Note that non-zero offsets are not currently supported.

```APIDOC
## rocfft_plan_description_set_data_layout

### Description
Set advanced data layout parameters on a plan description. This API specifies advanced layout of input/output buffers for a plan description. The following parameters are supported for inputs and outputs: Array type (real, hermitian, or complex data, in either interleaved or planar format). Real forward transforms require real input and hermitian output. Real inverse transforms require hermitian input and real output. Complex transforms require complex input and output. Hermitian and complex data defaults to interleaved if a specific format is not specified. Offset of first data element in the data buffer. Defaults to 0 if unspecified. Stride between consecutive elements in each dimension. Defaults to packed data layout consistent with the type of transform and its placement (requested at plan creation), if unspecified. Distance between consecutive batches. Zero values are interpreted as defaults to be deduced from the corresponding length and stride along the last transform dimension.
Not all combinations of array types are supported and error codes will be returned for unsupported cases. Offset, stride, and distance for either input or output provided here is ignored if a field is set for the corresponding input or output.
Note
Non-zero offsets are not supported yet.

### Parameters

#### Parameters
- **description** (rocfft_plan_description) - inout - description handle
- **in_array_type** (const rocfft_array_type) - in - array type of input buffer
- **out_array_type** (const rocfft_array_type) - in - array type of output buffer
- **in_offsets** (const size_t *) - in - offsets, in element units, to start of data in input buffer
- **out_offsets** (const size_t *) - in - offsets, in element units, to start of data in output buffer
- **in_strides_size** (const size_t) - in - size of in_strides array (must be equal to transform dimensions)
- **in_strides** (const size_t *) - in - array of strides, in each dimension, of input buffer; if set to null ptr library chooses defaults
- **in_distance** (const size_t) - in - distance between start of each data instance in input buffer
- **out_strides_size** (const size_t) - in - size of out_strides array (must be equal to transform dimensions)
- **out_strides** (const size_t *) - in - array of strides, in each dimension, of output buffer; if set to null ptr library chooses defaults
- **out_distance** (const size_t) - in - distance between start of each data instance in output buffer
```

--------------------------------

### rocfft_plan_description_add_outfield

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Adds a rocfft_field to a rocfft_plan_description as an output. This is part of an experimental API.

```APIDOC
## rocfft_plan_description_add_outfield

### Description
Add a rocfft_field to a rocfft_plan_description as an output. The field may be reused or freed immediately after the function returns.

**Warning**: Experimental! This feature is part of an experimental API preview.

### Parameters

* **description** – **[inout]** rocfft_plan_description that will pass the field information to plan creation
* **field** – **[in]** rocfft_field struct added as an output field
```

--------------------------------

### rocfft_plan_get_print

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Prints all information associated with an FFT plan to standard output. This function is useful for debugging purposes.

```APIDOC
## rocfft_plan_get_print

### Description
Print all plan information. Prints plan details to stdout, to aid debugging

### Parameters

#### Path Parameters
* **plan** (const rocfft_plan) - [in] plan handle

### Returns
rocfft_status - Status code indicating success or failure.
```

--------------------------------

### rocfft_plan_description_add_infield

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Adds a rocfft_field to a rocfft_plan_description as an input. This is part of an experimental API.

```APIDOC
## rocfft_plan_description_add_infield

### Description
Add a rocfft_field to a rocfft_plan_description as an input. The field may be reused or freed immediately after the function returns.

**Warning**: Experimental! This feature is part of an experimental API preview.

### Parameters

* **description** – **[inout]** rocfft_plan_description that will pass the field information to plan creation
* **field** – **[in]** rocfft_field struct added as an input field
```

--------------------------------

### Manage rocFFT Work Buffers Across Multiple HIP Devices

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/how-to/working-with-rocfft.html

This snippet demonstrates how to query and allocate work buffers for rocFFT plans when using multiple HIP devices. It iterates through each device, checks for required work buffer sizes, allocates memory if needed, and sets the buffer for the plan's execution info. Finally, it frees the allocated buffers.

```c++
rocfft_plan plan = nullptr;
rocfft_execution_info info = nullptr;

// For brevity, error checking and the steps to create the plan and
// execution info have been omitted

// Start on device 0
hipSetDevice(0);

// Get the number of HIP devices
int ndevices = 0;
hipGetDeviceCount(&ndevices);

// Loop over each device, checking work memory requirements for each one
std::vector<void*> workbufs(ndevices);
for(int device = 0; device < ndevices; ++device)
{
    hipSetDevice(device);
    size_t worksize = 0;
    // Get work memory size required for the current device
    rocfft_plan_get_work_buffer_size(plan, &worksize);
    if(worksize)
    {
        // Allocate and set the work buffer for the current device
        hipMalloc(&workbufs[device], worksize);
        rocfft_execution_info_set_work_buffer(info, workbufs[device], worksize);
    }
}

// Return to device 0
hipSetDevice(0);

// Execution of the plan with the execution info would happen here

// Free the work buffers that were allocated
for(int device = 0; device < ndevices; ++device)
{
    if(workbufs[device])
    {
        hipSetDevice(device);
        hipFree(workbufs[device]);
    }
}

// Return to device 0
hipSetDevice(0);

```

--------------------------------

### rocfft_brick_create

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Creates a brick object, which represents a sub-problem within a larger FFT.

```APIDOC
## rocfft_brick_create

### Description
Creates a brick object, which represents a sub-problem within a larger FFT.

### Method
`rocfft_brick_create(rocfft_brick *brick, const rocfft_brick_description desc)`

### Parameters
*   **brick** (rocfft_brick *) - Output parameter to store the created brick.
*   **desc** (const rocfft_brick_description) - Description of the brick.

### Response
#### Success Response
`rocfft_status_success` on successful brick creation.

#### Response Example
`rocfft_status_success`
```

--------------------------------

### rocfft_execution_info_set_load_callback

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Sets a load callback function for the execution info object.

```APIDOC
## rocfft_execution_info_set_load_callback

### Description
Sets a load callback function for the execution info object.

### Method
`rocfft_execution_info_set_load_callback(rocfft_execution_info exec_info, rocfft_callback load_callback)`

### Parameters
*   **exec_info** (rocfft_execution_info) - The execution info object.
*   **load_callback** (rocfft_callback) - The load callback function.

### Response
#### Success Response
`rocfft_status_success` if the load callback is set successfully.

#### Response Example
`rocfft_status_success`
```

--------------------------------

### rocfft_execution_info_create

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Creates an execution info object for rocFFT operations.

```APIDOC
## rocfft_execution_info_create

### Description
Creates an execution info object for rocFFT operations.

### Function Signature
```c
rocfft_status rocfft_execution_info_create(rocfft_execution_info* info);
```

### Parameters
- **info** (rocfft_execution_info*): Pointer to a `rocfft_execution_info` object to be created.

### Returns
- `rocfft_status_success` on success.
- `rocfft_status_failure` if creation fails.
```

--------------------------------

### rocfft_execution_info_set_store_callback

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Sets a store callback function for the execution info object.

```APIDOC
## rocfft_execution_info_set_store_callback

### Description
Sets a store callback function for the execution info object.

### Method
`rocfft_execution_info_set_store_callback(rocfft_execution_info exec_info, rocfft_callback store_callback)`

### Parameters
*   **exec_info** (rocfft_execution_info) - The execution info object.
*   **store_callback** (rocfft_callback) - The store callback function.

### Response
#### Success Response
`rocfft_status_success` if the store callback is set successfully.

#### Response Example
`rocfft_status_success`
```

--------------------------------

### Generate Test Coverage Report for rocFFT

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Generate a test coverage report for rocFFT, including samples and tests, and enable code coverage. The report is output to the terminal and saved as an HTML file in the current directory.

```bash
cmake -DCMAKE_CXX_COMPILER=amdclang++ -DBUILD_CLIENTS_SAMPLES=ON -DBUILD_CLIENTS_TESTS=ON -DBUILD_CODE_COVERAGE=ON <optional: -DCOVERAGE_TEST_OPTIONS="cmdline args to pass to rocfft-test (default: --smoketest)"> ..
make -j coverage
```

--------------------------------

### rocfft_execute

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Executes a Fast Fourier Transform using a given rocFFT plan and execution information.

```APIDOC
## rocfft_execute

### Description
Executes a Fast Fourier Transform using a given rocFFT plan and execution information.

### Function Signature
```c
rocfft_status rocfft_execute(rocfft_plan plan, void* input, void* output, rocfft_execution_info info);
```

### Parameters
- **plan** (rocfft_plan): The `rocfft_plan` object to use for the transform.
- **input** (void*): Pointer to the input data buffer.
- **output** (void*): Pointer to the output data buffer. Can be the same as the input buffer for in-place transforms.
- **info** (rocfft_execution_info): `rocfft_execution_info` object containing execution details like work buffer and stream.

### Returns
- `rocfft_status_success` on success.
- `rocfft_status_failure` if the execution fails.
```

--------------------------------

### rocfft_execute

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Executes a pre-defined FFT plan on specified input and output buffers. It allows for in-place or out-of-place transforms and can optionally use execution info for stream and work buffer control.

```APIDOC
## rocfft_execute

### Description
Executes an FFT plan on buffers provided by the user. Supports in-place transforms where only input buffers are needed, and out-of-place transforms requiring both input and output buffers. Handles interleaved and planar data formats, as well as fields.

### Method
rocfft_execute

### Parameters
#### Input Parameters
- **plan** (rocfft_plan) - Handle to the FFT plan to execute.
- **in_buffer** (void *[]) - Array of pointers to input buffers. Size varies based on data format (interleaved, planar, or field).
- **out_buffer** (void *[]) - Array of pointers to output buffers. Ignored for in-place transforms. Size varies based on data format.
- **info** (rocfft_execution_info) - Optional handle for execution information, such as stream and work buffer.

### Notes
Input buffers may be overwritten even for non-in-place transforms. Planar formats require two pointers per buffer (real and imaginary).
```

--------------------------------

### rocfft_plan_get_print

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Retrieves a function pointer to a print function associated with the rocFFT plan.

```APIDOC
## rocfft_plan_get_print

### Description
Retrieves a function pointer to a print function associated with the rocFFT plan.

### Function Signature
```c
rocfft_status rocfft_plan_get_print(rocfft_plan plan, rocfft_print_function* print_func);
```

### Parameters
- **plan** (rocfft_plan): The `rocfft_plan` object.
- **print_func** (rocfft_print_function*): Pointer to a `rocfft_print_function` variable where the function pointer will be stored.

### Returns
- `rocfft_status_success` on success.
- `rocfft_status_failure` if the operation fails.
```

--------------------------------

### rocfft_plan_description_set_data_layout

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Configures advanced data layout parameters for a plan description, including array types, offsets, strides, and distances for input and output buffers.

```APIDOC
## rocfft_plan_description_set_data_layout

### Description
Specifies advanced data layout configurations for input and output buffers within a plan description. This includes defining array types (real, hermitian, complex; interleaved or planar), offsets, strides, and distances between batches.

### Method
`rocfft_plan_description_set_data_layout`

### Parameters
#### Input Parameters
- **description** (rocfft_plan_description) - Input - Description handle.
- **in_array_type** (rocfft_array_type) - Input - Array type for input data.
- **out_array_type** (rocfft_array_type) - Input - Array type for output data.
- **in_offsets** (const size_t *) - Input - Offsets for input data elements.
- **out_offsets** (const size_t *) - Input - Offsets for output data elements.
- **in_strides_size** (const size_t) - Input - Size of the input strides array.
- **in_strides** (const size_t *) - Input - Strides between consecutive input elements in each dimension.
- **in_distance** (const size_t) - Input - Distance between consecutive input batches.
- **out_strides_size** (const size_t) - Input - Size of the output strides array.
- **out_strides** (const size_t *) - Input - Strides between consecutive output elements in each dimension.
- **out_distance** (const size_t) - Input - Distance between consecutive output batches.

### Notes
- Supported array types include real, hermitian, and complex data in interleaved or planar formats.
- Real forward transforms require real input and hermitian output; real inverse transforms require hermitian input and real output.
- Defaults are used if parameters are unspecified (e.g., offset to 0, stride to packed layout, distance to deduced value).
- Non-zero offsets are not currently supported.
- Offsets, strides, and distances for input/output are ignored if a field is set for the corresponding input or output.
```

--------------------------------

### rocfft_plan_description_set_data_layout

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Sets the data layout for a rocFFT plan description.

```APIDOC
## rocfft_plan_description_set_data_layout

### Description
Sets the data layout for a rocFFT plan description.

### Function Signature
```c
rocfft_status rocfft_plan_description_set_data_layout(rocfft_plan_description desc, rocfft_array_type array_type, rocfft_result_placement placement);
```

### Parameters
- **desc** (rocfft_plan_description): The `rocfft_plan_description` object.
- **array_type** (rocfft_array_type): The type of the array (e.g., `rocfft_array_type_complex_interleaved`).
- **placement** (rocfft_result_placement): The result placement (e.g., `rocfft_placement_inplace`).

### Returns
- `rocfft_status_success` on success.
- `rocfft_status_failure` if setting the data layout fails.
```

--------------------------------

### Execution

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Functions related to executing FFT transforms and managing execution information.

```APIDOC
## rocfft_execute()

### Description
Executes the FFT transform defined by the given plan. This function performs the actual computation.

### Method
rocfft_execute

### Parameters
* **plan** (rocfft_plan) - The plan handle for the FFT transform.
* **exec_info** (rocfft_execution_info) - Execution information, including work buffer and stream.

### Response
* **rocfft_status** - Status code indicating success or failure.

## rocfft_execution_info_create()

### Description
Creates an execution info object, which holds details like the work buffer and HIP stream for an FFT execution.

### Method
rocfft_execution_info_create

### Parameters
* **exec_info** (rocfft_execution_info**) - Output parameter to store the created execution info handle.

### Response
* **rocfft_status** - Status code indicating success or failure.

## rocfft_execution_info_destroy()

### Description
Destroys an execution info object, releasing its resources.

### Method
rocfft_execution_info_destroy

### Parameters
* **exec_info** (rocfft_execution_info) - The execution info handle to destroy.

### Response
* **rocfft_status** - Status code indicating success or failure.

## rocfft_execution_info_set_work_buffer()

### Description
Sets the work buffer to be used for the FFT execution. This buffer is used for intermediate storage during computation.

### Method
rocfft_execution_info_set_work_buffer

### Parameters
* **exec_info** (rocfft_execution_info) - The execution info handle.
* **work_buffer** (void*) - Pointer to the work buffer.
* **size_in_bytes** (size_t) - The size of the work buffer in bytes.

### Response
* **rocfft_status** - Status code indicating success or failure.

## rocfft_execution_info_set_stream()

### Description
Sets the HIP stream on which the FFT execution will be enqueued. This allows for asynchronous execution and synchronization.

### Method
rocfft_execution_info_set_stream

### Parameters
* **exec_info** (rocfft_execution_info) - The execution info handle.
* **stream** (hipStream_t) - The HIP stream to use for execution.

### Response
* **rocfft_status** - Status code indicating success or failure.
```

--------------------------------

### Set Compute Stream in Execution Info

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/api.html

Associates a compute stream (hipStream_t) with the plan execution. The FFT computation will run through the specified stream. Must be called before rocfft_execute.

```c
rocfft_status rocfft_execution_info_set_stream(rocfft_execution_info info, void *stream)
```

--------------------------------

### rocfft_execution_info_set_store_callback

Source: https://rocm.docs.amd.com/projects/rocFFT/en/latest/reference/allapi.html

Sets a user-defined callback function to store output to global memory at the end of the transform. This is an experimental feature. Store callbacks require at least one brick on the output field and all functions in the array must perform the same logical operation.

```APIDOC
## rocfft_execution_info_set_store_callback

### Description
Sets a user-defined callback function to store output to global memory at the end of the transform. This is an experimental feature. Store callbacks require at least one brick on the output field and all functions in the array must perform the same logical operation. A null value for 'cb_functions' clears any previously registered store callback.

### Method
Not specified (likely a C function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **info** (rocfft_execution_info) - Required - execution info handle
- **cb_functions** (void**) - Required - callback function pointers
- **cb_data** (void**) - Optional - callback function data, passed to the function pointer when it is called
- **shared_mem_bytes** (size_t) - Required - amount of shared memory to allocate for the callback function to use (must be 0 currently)
```
Tokens:
Raw