muFFT API Reference

This document describes the muFFT APIs supported in MUSA SDK 5.2. It is organized into three parts: Introduction, Using the muFFT API, and API Reference.

1. Introduction

1.1 What Is muFFT

muFFT is the MUSA Fast Fourier Transform library. It provides FFT interfaces for one-dimensional, two-dimensional, and three-dimensional transforms on MTGPU devices. muFFT supports complex-to-complex, real-to-complex, and complex-to-real transforms. It also provides APIs for batched execution, explicit plan management, workspace control, stream association, and selected Xt multi-GPU workflows.

For most applications, the muFFT programming model is straightforward:

Choose the transform type, dimensions, and data layout.
Create or configure a plan.
Query and provide workspace if needed.
Execute the transform on device data.
Reuse or destroy the plan.

1.2 Supported Transform Types

Transform type	Description	Execution API
`MUFFT_C2C`	Single-precision complex-to-complex	`mufftExecC2C`
`MUFFT_Z2Z`	Double-precision complex-to-complex	`mufftExecZ2Z`
`MUFFT_R2C`	Single-precision real-to-complex	`mufftExecR2C`
`MUFFT_C2R`	Single-precision complex-to-real	`mufftExecC2R`
`MUFFT_D2Z`	Double-precision real-to-complex	`mufftExecD2Z`
`MUFFT_Z2D`	Double-precision complex-to-real	`mufftExecZ2D`

muFFT uses mufftType to select the transform type. Use MUFFT_FORWARD and MUFFT_INVERSE to specify transform direction. For real-to-complex and complex-to-real transforms, the direction parameter may be ignored, depending on the execution path.

1.3 Supported Dimensions

MUSA SDK 5.2 covers the following plan shapes:

One-dimensional plans: mufftPlan1d, mufftMakePlan1d
Two-dimensional plans: mufftPlan2d, mufftMakePlan2d
Three-dimensional plans: mufftPlan3d, mufftMakePlan3d
Rank-based and batched plans: mufftPlanMany, mufftMakePlanMany

For two-dimensional and three-dimensional data, the muFFT headers define the default layout as C order, or row-major order. In 2D transforms, y is the fastest-varying dimension. In 3D transforms, z is the fastest-varying dimension.

1.4 Batch Processing

muFFT supports batched execution. Common entry points include mufftPlan1d(..., batch) and mufftPlanMany(..., batch).

If your input and output use the default contiguous layout, the batch parameter is often sufficient. If you need explicit control over batch spacing or a nondefault tensor layout, use mufftPlanMany or mufftMakePlanMany and provide:

inembed and onembed
istride and ostride
idist and odist

1.5 Document Scope in MUSA SDK 5.2

This reference describes the muFFT APIs supported in MUSA SDK 5.2. Only the APIs and usage paths documented here are supported in this release.

Note: Other muFFT APIs may appear in the public headers. If they are not documented in this reference, treat them as experimental in MUSA SDK 5.2.

1.6 How to Read This Document

Start with Using the muFFT API to understand the planning and execution model. Use API Reference to confirm a function signature, data type, return value, or usage constraint.

2. Using the muFFT API

2.1 Plan Lifecycle

muFFT provides two planning paths: basic plans and extensible plans.

Use the basic planning path when the default plan setup is sufficient:

Call mufftPlan1d, mufftPlan2d, mufftPlan3d, or mufftPlanMany.
Receive a ready-to-execute plan.
Execute the transform with the corresponding mufftExec* API.
Destroy the plan with mufftDestroy.

Use the extensible planning path when you need explicit control over plan setup:

Call mufftCreate to create an empty plan handle.
If multi-GPU execution is needed, call mufftXtSetGPUs.
Call mufftMakePlan1d, mufftMakePlan2d, mufftMakePlan3d, or mufftMakePlanMany.
Query workspace requirements if needed.
Execute the transform.
Destroy the plan with mufftDestroy.

Use mufftPlan* for direct plan creation. Use mufftCreate with mufftMakePlan* when you need explicit setup, workspace control, or Xt multi-GPU configuration.

2.2 Data Layout and Workspace

Correct data layout is required for successful execution.

The default layout rules are:

mufftPlan2d assumes row-major 2D data with y as the fastest-varying dimension.
mufftPlan3d assumes row-major 3D data with z as the fastest-varying dimension.

When the default contiguous layout is not sufficient, use mufftPlanMany or mufftMakePlanMany to describe the layout explicitly:

Parameter group	Purpose
`inembed`, `onembed`	Logical storage dimensions of the input and output
`istride`, `ostride`	Distance between adjacent elements in the innermost dimension
`idist`, `odist`	Distance between adjacent batches

Workspace APIs fall into three groups:

API group	Purpose
`mufftEstimate1d`, `mufftEstimate2d`, `mufftEstimate3d`, `mufftEstimateMany`	Coarse workspace estimation before final plan setup
`mufftGetSize1d`, `mufftGetSize2d`, `mufftGetSize3d`, `mufftGetSizeMany`	Refined workspace query for a specific plan configuration
`mufftGetSize`	Query the workspace size of an existing plan

If you need caller-managed workspace, use this flow:

Read the required size from workSize, mufftGetSize*, or mufftGetSize.
Allocate device memory for the workspace.
Bind the workspace with mufftSetWorkArea.

2.3 Stream Usage

Use mufftSetStream to associate a plan with a specific musaStream_t. After you set the stream, kernels launched through that plan run on the selected stream.

Recommended usage:

Set the stream after the plan has been created and configured.
Prefer multiple reusable plans when you need concurrent execution on multiple streams.
Check stream association first when debugging execution ordering or overlap behavior.

2.4 Xt Multi-GPU Usage

MUSA SDK 5.2 supports a subset of the muFFT Xt multi-GPU API.

Use this flow:

Call mufftCreate.
Call mufftXtSetGPUs to select the participating GPUs.
Call mufftMakePlan*.
Call mufftXtMalloc to allocate a musaLibXtDesc and its associated device memory.
Call mufftXtMemcpy to move data between host memory and the descriptor-backed device memory.
Execute the transform with mufftXtExec or mufftXtExecDescriptor*.
Release the descriptor with mufftXtFree.

Two constraints matter most:

mufftXtSetGPUs must be called after mufftCreate and before mufftMakePlan*.
mufftXtExecDescriptor* supports only in-place multi-GPU execution, so input and output must refer to the same descriptor.

The following Xt execution APIs are supported in this release:

Generic execution: mufftXtExec, mufftXtExecDescriptor
Single-precision complex: mufftXtExecDescriptorC2C
Double-precision complex: mufftXtExecDescriptorZ2Z
Single-precision real and complex conversion: mufftXtExecDescriptorR2C, mufftXtExecDescriptorC2R
Double-precision real and complex conversion: mufftXtExecDescriptorD2Z, mufftXtExecDescriptorZ2D

2.5 Callback Usage

MUSA SDK 5.2 supports mufftXtSetCallback and mufftXtClearCallback with these limitations:

mufftXtSetCallback is valid only after mufftMakePlan*.
Shared-memory callbacks are not supported.
Multi-GPU callback usage is not supported.

Use the following flow:

Complete plan creation with mufftCreate and mufftMakePlan*.
Prepare the callback routine pointer array.
Provide caller_info device pointers if your callback implementation requires them.
Register the callback with mufftXtSetCallback.
Remove the callback with mufftXtClearCallback when it is no longer needed.

2.6 Examples

The following example shows a minimal 1D complex-to-complex transform.

2.6.1 1D C2C Example

#include <musa_runtime.h>
#include <mufft.h>

int main() {
    const int n = 1024;
    mufftHandle plan;
    mufftComplex* data = nullptr;

    musaMalloc(&data, n * sizeof(mufftComplex));

    mufftPlan1d(&plan, n, MUFFT_C2C, 1);
    mufftExecC2C(plan, data, data, MUFFT_FORWARD);

    mufftDestroy(plan);
    musaFree(data);
    return 0;
}

This example shows the basic sequence:

Create a 1D complex-to-complex plan
Execute the transform in place
Destroy the plan and release device memory

2.7 Performance Tips

Reuse plans whenever possible. Plan creation is often more expensive than execution.
Prefer batch execution when multiple transforms share the same shape and layout.
Define layout parameters carefully before using mufftPlanMany; layout debugging is usually more expensive than getting the data model right up front.
Query workspace once and allocate it consistently when using caller-managed workspace.
Use Xt multi-GPU execution only when the problem size and decomposition benefits justify the added complexity.

2.8 Error Handling

mufftResult is the primary return type for muFFT APIs. The most common status codes are:

Return value	Meaning	Typical cause
`MUFFT_INVALID_PLAN`	Invalid plan handle	The plan was not created, was destroyed, or is used in the wrong state
`MUFFT_ALLOC_FAILED`	Allocation failed	Plan setup or device memory allocation failed
`MUFFT_INVALID_TYPE`	Invalid type	An unsupported `mufftType` or property type was provided
`MUFFT_INVALID_VALUE`	Invalid value	A pointer, dimension, or layout parameter is invalid
`MUFFT_INVALID_SIZE`	Invalid size	The transform size or batch count is not supported
`MUFFT_NO_WORKSPACE`	Missing workspace	Caller-managed workspace is required but not correctly bound
`MUFFT_EXEC_FAILED`	Execution failed	The transform could not complete on the device
`MUFFT_NOT_SUPPORTED`	Not supported	The requested parameter combination or feature path is not supported

For Xt and callback issues, verify the required call order and supported usage constraints before debugging individual parameters.

3. API Reference

This chapter describes the supported muFFT library functions, including their parameters, data types, return values, and usage constraints. Only the muFFT APIs supported in MUSA SDK 5.2 are included in this reference. APIs that may appear in the public headers but are not documented here should be treated as experimental in this release.

3.1 Return Value `mufftResult`

This section documents mufftResult_t and mufftResult, the return type and status-code definitions used throughout the muFFT API.

3.2 muFFT Basic Plans

These routines allocate and initialize a mufftHandle for the requested transform configuration. All functions in this section return mufftResult.

`mufftPlan1d`

mufftResult mufftPlan1d(mufftHandle* plan, int nx, mufftType type, int batch)

Creates and initializes a one-dimensional FFT plan.

Parameters:

plan: Receives the FFT plan handle.
nx: FFT length.
type: Transform type.
batch: Number of batched transforms to compute.

`mufftPlan2d`

mufftResult mufftPlan2d(mufftHandle* plan, int nx, int ny, mufftType type)

Creates and initializes a two-dimensional FFT plan. Two-dimensional data is interpreted in row-major order, with y as the fastest-varying dimension.

Parameters:

plan: Receives the FFT plan handle.
nx: Number of elements in the x-dimension.
ny: Number of elements in the y-dimension.
type: Transform type.

`mufftPlan3d`

mufftResult mufftPlan3d(mufftHandle* plan, int nx, int ny, int nz, mufftType type)

Creates and initializes a three-dimensional FFT plan. Three-dimensional data is interpreted in row-major order, with z as the fastest-varying dimension.

Parameters:

plan: Receives the FFT plan handle.
nx: Number of elements in the x-dimension.
ny: Number of elements in the y-dimension.
nz: Number of elements in the z-dimension.
type: Transform type.

`mufftPlanMany`

mufftResult mufftPlanMany(
    mufftHandle* plan,
    int rank,
    int* n,
    int* inembed,
    int istride,
    int idist,
    int* onembed,
    int ostride,
    int odist,
    mufftType type,
    int batch)

Creates and initializes a batched rank-dimensional FFT plan. Use this routine when you need explicit control over data layout.

Parameters:

plan: Receives the FFT plan handle.
rank: Transform rank. Supported values are 1, 2, and 3.
n: Logical transform size for each dimension.
inembed: Logical input storage dimensions. If NULL, the default contiguous layout is used.
istride: Distance between adjacent input elements in the innermost dimension.
idist: Distance between consecutive input batches.
onembed: Logical output storage dimensions. If NULL, the default contiguous layout is used.
ostride: Distance between adjacent output elements in the innermost dimension.
odist: Distance between consecutive output batches.
type: Transform type.
batch: Number of batched transforms.

3.3 muFFT Extensible Plans

These routines separate handle creation from plan generation. Use them when plan creation, optional GPU selection, and final plan generation must occur in separate steps. All functions in this section return mufftResult.

`mufftCreate`

mufftResult mufftCreate(mufftHandle* plan)

Creates an opaque plan handle. Complete plan generation with a later mufftMakePlan* call.

Parameters:

plan: Receives the mufftHandle.

`mufftMakePlan1d`

mufftResult mufftMakePlan1d(
    mufftHandle plan,
    int nx,
    mufftType type,
    int batch,
    size_t* workSize)

Initializes a one-dimensional FFT plan on an existing handle.

Parameters:

plan: Existing FFT plan handle created by mufftCreate.
nx: FFT length.
type: Transform type.
batch: Number of batched transforms to compute.
workSize: Returns the required work area size in bytes.

`mufftMakePlan2d`

mufftResult mufftMakePlan2d(
    mufftHandle plan,
    int nx,
    int ny,
    mufftType type,
    size_t* workSize)

Initializes a two-dimensional FFT plan on an existing handle. Two-dimensional data is interpreted in row-major order, with y as the fastest-varying dimension.

Parameters:

plan: Existing FFT plan handle created by mufftCreate.
nx: Number of elements in the x-dimension.
ny: Number of elements in the y-dimension.
type: Transform type.
workSize: Returns the required work area size in bytes.

`mufftMakePlan3d`

mufftResult mufftMakePlan3d(
    mufftHandle plan,
    int nx,
    int ny,
    int nz,
    mufftType type,
    size_t* workSize)

Initializes a three-dimensional FFT plan on an existing handle. Three-dimensional data is interpreted in row-major order, with z as the fastest-varying dimension.

Parameters:

plan: Existing FFT plan handle created by mufftCreate.
nx: Number of elements in the x-dimension.
ny: Number of elements in the y-dimension.
nz: Number of elements in the z-dimension.
type: Transform type.
workSize: Returns the required work area size in bytes.

`mufftMakePlanMany`

mufftResult mufftMakePlanMany(
    mufftHandle plan,
    int rank,
    int* n,
    int* inembed,
    int istride,
    int idist,
    int* onembed,
    int ostride,
    int odist,
    mufftType type,
    int batch,
    size_t* workSize)

Initializes a batched rank-dimensional FFT plan on an existing handle.

Parameters:

plan: Existing FFT plan handle created by mufftCreate.
rank: Transform rank. Supported values are 1, 2, and 3.
n: Logical transform size for each dimension.
inembed: Logical input storage dimensions. If NULL, the default contiguous layout is used.
istride: Distance between adjacent input elements in the innermost dimension.
idist: Distance between consecutive input batches.
onembed: Logical output storage dimensions. If NULL, the default contiguous layout is used.
ostride: Distance between adjacent output elements in the innermost dimension.
odist: Distance between consecutive output batches.
type: Transform type.
batch: Number of batched transforms.
workSize: Returns the required work area size in bytes.

`mufftDestroy`

mufftResult mufftDestroy(mufftHandle plan)

Destroys a plan and releases its associated resources.

Parameters:

plan: Plan handle to destroy.

3.4 muFFT Plan Properties

MUSA SDK 5.2 does not document a separate plan-property API group. Plan behavior is defined by the planning APIs and, where applicable, mufftXtSetGPUs.

3.5 muFFT Estimated Size of Work Area

These routines estimate work area requirements before final plan generation. All functions in this section return mufftResult.

`mufftEstimate1d`

mufftResult mufftEstimate1d(int nx, mufftType type, int batch, size_t* workSize)

Estimates the work area size required for a one-dimensional plan.

Parameters:

nx: FFT length.
type: Transform type.
batch: Number of batched transforms.
workSize: Returns the estimated work area size in bytes.

`mufftEstimate2d`

mufftResult mufftEstimate2d(int nx, int ny, mufftType type, size_t* workSize)

Estimates the work area size required for a two-dimensional plan.

Parameters:

nx: Number of elements in the x-dimension.
ny: Number of elements in the y-dimension.
type: Transform type.
workSize: Returns the estimated work area size in bytes.

`mufftEstimate3d`

mufftResult mufftEstimate3d(int nx, int ny, int nz, mufftType type, size_t* workSize)

Estimates the work area size required for a three-dimensional plan.

Parameters:

nx: Number of elements in the x-dimension.
ny: Number of elements in the y-dimension.
nz: Number of elements in the z-dimension.
type: Transform type.
workSize: Returns the estimated work area size in bytes.

`mufftEstimateMany`

mufftResult mufftEstimateMany(
    int rank,
    int* n,
    int* inembed,
    int istride,
    int idist,
    int* onembed,
    int ostride,
    int odist,
    mufftType type,
    int batch,
    size_t* workSize)

Estimates the work area size required for a rank-dimensional plan with explicit layout control.

Parameters:

rank: Transform rank. Supported values are 1, 2, and 3.
n: Logical transform size for each dimension.
inembed: Logical input storage dimensions. If NULL, the default contiguous layout is used.
istride: Distance between adjacent input elements in the innermost dimension.
idist: Distance between consecutive input batches.
onembed: Logical output storage dimensions. If NULL, the default contiguous layout is used.
ostride: Distance between adjacent output elements in the innermost dimension.
odist: Distance between consecutive output batches.
type: Transform type.
batch: Number of batched transforms.
workSize: Returns the estimated work area size in bytes.

3.6 muFFT Refined Estimated Size of Work Area

These routines return refined work area requirements for specific plan configurations. All functions in this section return mufftResult.

`mufftGetSize1d`

mufftResult mufftGetSize1d(
    mufftHandle plan,
    int nx,
    mufftType type,
    int batch,
    size_t* workSize)

Returns the refined work area size required for a one-dimensional plan configuration.

Parameters:

plan: FFT plan handle.
nx: FFT length.
type: Transform type.
batch: Number of batched transforms.
workSize: Returns the required work area size in bytes.

`mufftGetSize2d`

mufftResult mufftGetSize2d(
    mufftHandle plan,
    int nx,
    int ny,
    mufftType type,
    size_t* workSize)

Returns the refined work area size required for a two-dimensional plan configuration.

Parameters:

plan: FFT plan handle.
nx: Number of elements in the x-dimension.
ny: Number of elements in the y-dimension.
type: Transform type.
workSize: Returns the required work area size in bytes.

`mufftGetSize3d`

mufftResult mufftGetSize3d(
    mufftHandle plan,
    int nx,
    int ny,
    int nz,
    mufftType type,
    size_t* workSize)

Returns the refined work area size required for a three-dimensional plan configuration.

Parameters:

plan: FFT plan handle.
nx: Number of elements in the x-dimension.
ny: Number of elements in the y-dimension.
nz: Number of elements in the z-dimension.
type: Transform type.
workSize: Returns the required work area size in bytes.

`mufftGetSizeMany`

mufftResult mufftGetSizeMany(
    mufftHandle plan,
    int rank,
    int* n,
    int* inembed,
    int istride,
    int idist,
    int* onembed,
    int ostride,
    int odist,
    mufftType type,
    int batch,
    size_t* workSize)

Returns the refined work area size required for a rank-dimensional plan configuration.

Parameters:

plan: FFT plan handle.
rank: Transform rank. Supported values are 1, 2, and 3.
n: Logical transform size for each dimension.
inembed: Logical input storage dimensions. If NULL, the default contiguous layout is used.
istride: Distance between adjacent input elements in the innermost dimension.
idist: Distance between consecutive input batches.
onembed: Logical output storage dimensions. If NULL, the default contiguous layout is used.
ostride: Distance between adjacent output elements in the innermost dimension.
odist: Distance between consecutive output batches.
type: Transform type.
batch: Number of batched transforms.
workSize: Returns the required work area size in bytes.

3.7 `mufftGetSize()`

This routine returns the workspace size for an existing plan.

`mufftGetSize`

mufftResult mufftGetSize(mufftHandle plan, size_t* workSize)

Returns the current work area size for an existing plan.

Parameters:

plan: FFT plan handle.
workSize: Returns the work area size, in bytes.

3.8 muFFT Caller Allocated Work Area Support

This section describes how to attach caller-allocated workspace to an existing plan after the required size has been determined.

`mufftSetWorkArea`

mufftResult mufftSetWorkArea(mufftHandle plan, void* workArea)

Associates caller-allocated device workspace with an existing plan.

Parameters:

plan: FFT plan handle.
workArea: Device pointer to the work area buffer.

3.9 muFFT Execution

These routines execute FFT operations for the supported transform types. All functions in this section return mufftResult.

`mufftExecC2C`

mufftResult mufftExecC2C(
    mufftHandle plan,
    mufftComplex* idata,
    mufftComplex* odata,
    int direction)

Executes a single-precision complex-to-complex transform. If idata and odata are the same pointer, the transform is performed in place.

Parameters:

plan: FFT plan handle.
idata: Input device pointer.
odata: Output device pointer.
direction: MUFFT_FORWARD or MUFFT_INVERSE.

`mufftExecZ2Z`

mufftResult mufftExecZ2Z(
    mufftHandle plan,
    mufftDoubleComplex* idata,
    mufftDoubleComplex* odata,
    int direction)

Executes a double-precision complex-to-complex transform. If idata and odata are the same pointer, the transform is performed in place.

Parameters:

plan: FFT plan handle.
idata: Input device pointer.
odata: Output device pointer.
direction: MUFFT_FORWARD or MUFFT_INVERSE.

`mufftExecR2C`

mufftResult mufftExecR2C(
    mufftHandle plan,
    mufftReal* idata,
    mufftComplex* odata)

Executes a single-precision real-to-complex transform. If idata and odata alias the same storage, the transform is performed in place.

Parameters:

plan: FFT plan handle.
idata: Input device pointer.
odata: Output device pointer.

`mufftExecD2Z`

mufftResult mufftExecD2Z(
    mufftHandle plan,
    mufftDoubleReal* idata,
    mufftDoubleComplex* odata)

Executes a double-precision real-to-complex transform. If idata and odata alias the same storage, the transform is performed in place.

Parameters:

plan: FFT plan handle.
idata: Input device pointer.
odata: Output device pointer.

`mufftExecC2R`

mufftResult mufftExecC2R(
    mufftHandle plan,
    mufftComplex* idata,
    mufftReal* odata)

Executes a single-precision complex-to-real transform. If idata and odata alias the same storage, the transform is performed in place.

Parameters:

plan: FFT plan handle.
idata: Input device pointer.
odata: Output device pointer.

`mufftExecZ2D`

mufftResult mufftExecZ2D(
    mufftHandle plan,
    mufftDoubleComplex* idata,
    mufftDoubleReal* odata)

Executes a double-precision complex-to-real transform. If idata and odata alias the same storage, the transform is performed in place.

Parameters:

plan: FFT plan handle.
idata: Input device pointer.
odata: Output device pointer.

3.10 muFFT and Multiple GPUs

These routines configure and execute the supported Xt multi-GPU workflows. All functions in this section return mufftResult.

`mufftXtSetGPUs`

mufftResult mufftXtSetGPUs(mufftHandle plan, int nGPUs, int* whichGPUs)

Selects the GPUs used by an Xt plan. Call this routine after mufftCreate and before mufftMakePlan*.

Parameters:

plan: FFT plan handle created by mufftCreate.
nGPUs: Number of GPUs to use.
whichGPUs: Array of device indices. The array order defines GPU ordering for data decomposition.

`mufftXtMalloc`

mufftResult mufftXtMalloc(
    mufftHandle plan,
    musaLibXtDesc** descriptor,
    mufftXtSubFormat format)

Allocates a multi-GPU descriptor and the associated device memory.

Parameters:

plan: FFT plan handle created by mufftCreate.
descriptor: Receives the allocated musaLibXtDesc.
format: Descriptor layout format.

`mufftXtFree`

mufftResult mufftXtFree(musaLibXtDesc* descriptor)

Releases a descriptor previously allocated by mufftXtMalloc.

Parameters:

descriptor: Descriptor to free.

`mufftXtMemcpy`

mufftResult mufftXtMemcpy(
    mufftHandle plan,
    void* dstPointer,
    void* srcPointer,
    mufftXtCopyType type)

Copies data between host buffers and descriptor-backed device memory, or between GPUs.

Parameters:

plan: FFT plan handle created by mufftCreate.
dstPointer: Destination address.
srcPointer: Source address.
type: Copy direction and transfer type.

`mufftXtExec`

mufftResult mufftXtExec(
    mufftHandle plan,
    void* input,
    void* output,
    int direction)

Executes an Xt transform for any supported precision and type. For real-to-complex and complex-to-real transforms, direction is ignored.

Parameters:

plan: FFT plan handle.
input: Input device pointer.
output: Output device pointer.
direction: MUFFT_FORWARD or MUFFT_INVERSE.

`mufftXtExecDescriptor`

mufftResult mufftXtExecDescriptor(
    mufftHandle plan,
    musaLibXtDesc* input,
    musaLibXtDesc* output,
    int direction)

Executes an Xt transform using descriptor-backed multi-GPU memory. Only in-place multi-GPU execution is supported, so input and output must refer to the same descriptor.

Parameters:

plan: FFT plan handle.
input: Input descriptor.
output: Output descriptor.
direction: MUFFT_FORWARD or MUFFT_INVERSE.

`mufftXtExecDescriptorC2C`

mufftResult mufftXtExecDescriptorC2C(
    mufftHandle plan,
    musaLibXtDesc* input,
    musaLibXtDesc* output,
    int direction)

Executes a single-precision complex-to-complex Xt transform. Only in-place multi-GPU execution is supported.

Parameters:

plan: FFT plan handle.
input: Input descriptor.
output: Output descriptor.
direction: MUFFT_FORWARD or MUFFT_INVERSE.

`mufftXtExecDescriptorZ2Z`

mufftResult mufftXtExecDescriptorZ2Z(
    mufftHandle plan,
    musaLibXtDesc* input,
    musaLibXtDesc* output,
    int direction)

Executes a double-precision complex-to-complex Xt transform. Only in-place multi-GPU execution is supported.

Parameters:

plan: FFT plan handle.
input: Input descriptor.
output: Output descriptor.
direction: MUFFT_FORWARD or MUFFT_INVERSE.

`mufftXtExecDescriptorR2C`

mufftResult mufftXtExecDescriptorR2C(
    mufftHandle plan,
    musaLibXtDesc* input,
    musaLibXtDesc* output)

Executes a single-precision real-to-complex Xt transform. Only in-place multi-GPU execution is supported.

Parameters:

plan: FFT plan handle.
input: Input descriptor.
output: Output descriptor.

`mufftXtExecDescriptorD2Z`

mufftResult mufftXtExecDescriptorD2Z(
    mufftHandle plan,
    musaLibXtDesc* input,
    musaLibXtDesc* output)

Executes a double-precision real-to-complex Xt transform. Only in-place multi-GPU execution is supported.

Parameters:

plan: FFT plan handle.
input: Input descriptor.
output: Output descriptor.

`mufftXtExecDescriptorC2R`

mufftResult mufftXtExecDescriptorC2R(
    mufftHandle plan,
    musaLibXtDesc* input,
    musaLibXtDesc* output)

Executes a single-precision complex-to-real Xt transform. Only in-place multi-GPU execution is supported.

Parameters:

plan: FFT plan handle.
input: Input descriptor.
output: Output descriptor.

`mufftXtExecDescriptorZ2D`

mufftResult mufftXtExecDescriptorZ2D(
    mufftHandle plan,
    musaLibXtDesc* input,
    musaLibXtDesc* output)

Executes a double-precision complex-to-real Xt transform. Only in-place multi-GPU execution is supported.

Parameters:

plan: FFT plan handle.
input: Input descriptor.
output: Output descriptor.

3.11 muFFT Callbacks

These routines register and remove the callback APIs available in MUSA SDK 5.2. All functions in this section return mufftResult.

`mufftXtSetCallback`

mufftResult mufftXtSetCallback(
    mufftHandle plan,
    void** callback_routine,
    mufftXtCallbackType cbType,
    void** caller_info)

Registers a load or store callback on an Xt plan. Call this routine only after mufftMakePlan*. Shared-memory callbacks and multi-GPU callback execution are not supported in MUSA SDK 5.2.

Parameters:

plan: FFT plan handle created by mufftCreate.
callback_routine: Array of callback routine pointers, one per GPU.
cbType: Callback type to register.
caller_info: Optional array of device pointers to caller-defined data, one per GPU.

`mufftXtClearCallback`

mufftResult mufftXtClearCallback(mufftHandle plan, mufftXtCallbackType cbType)

Removes the specified callback from a plan.

Parameters:

plan: FFT plan handle created by mufftCreate.
cbType: Callback type to clear.

3.12 `mufftSetStream()`

This routine associates a plan with an execution stream.

`mufftSetStream`

mufftResult mufftSetStream(mufftHandle plan, musaStream_t stream)

Associates a MUSA stream with a muFFT plan. Kernels launched through that plan run on the specified stream.

Parameters:

plan: FFT plan handle.
stream: MUSA stream to associate with the plan.

3.13 `mufftGetVersion()`

This routine returns the muFFT library version number.

`mufftGetVersion`

mufftResult mufftGetVersion(int* version)

Queries the muFFT library version.

Parameters:

version: Receives the library version.

3.14 `mufftGetProperty()`

This routine queries muFFT library properties identified by libraryPropertyType.

`mufftGetProperty`

mufftResult mufftGetProperty(libraryPropertyType type, int* value)

Queries a library property identified by libraryPropertyType.

Parameters:

type: Property type to query.
value: Receives the property value.

3.15 muFFT Types

This section documents mufftType_t and mufftType, which define the transform types accepted by the planning and execution APIs.

The supported transform type mapping is:

Enumerator	Meaning
`MUFFT_R2C`	Single-precision real-to-complex
`MUFFT_C2R`	Single-precision complex-to-real
`MUFFT_C2C`	Single-precision complex-to-complex
`MUFFT_D2Z`	Double-precision real-to-complex
`MUFFT_Z2D`	Double-precision complex-to-real
`MUFFT_Z2Z`	Double-precision complex-to-complex

3.16 Common Types

This section documents the common handle, scalar, and complex types used throughout the public muFFT API:

mufftHandle
mufftReal
mufftDoubleReal
mufftComplex
mufftDoubleComplex

`mufftHandle`

mufftHandle is an opaque plan handle. Applications receive it when a plan is created and use it to configure, execute, query, and destroy the plan.

`mufftReal`

mufftReal is the single-precision real scalar type used by single-precision real-input and real-output transforms.

`mufftDoubleReal`

mufftDoubleReal is the double-precision real scalar type used by double-precision real-input and real-output transforms.

`mufftComplex`

mufftComplex is the single-precision complex type. It stores interleaved real and imaginary components.

`mufftDoubleComplex`

mufftDoubleComplex is the double-precision complex type. It stores interleaved real and imaginary components.

这篇文章对您有帮助吗？

摩尔线程和摩尔线程徽标是摩尔线程智能科技 (北京)有限责任公司的注册商标。

免责声明

本文档提供有关摩尔线程产品的信息。本文档并未授权任何知识产权的许可，并未以明示或暗示，或以禁止反言或其他方式授予任何知识产权许可。

1. Introduction
2. Using the muFFT API
3. API Reference

1. Introduction​

1.1 What Is muFFT​

1.2 Supported Transform Types​

1.3 Supported Dimensions​

1.4 Batch Processing​

1.5 Document Scope in MUSA SDK 5.2​

1.6 How to Read This Document​

2. Using the muFFT API​

2.1 Plan Lifecycle​

2.2 Data Layout and Workspace​

2.3 Stream Usage​

2.4 Xt Multi-GPU Usage​

2.5 Callback Usage​

2.6 Examples​

2.6.1 1D C2C Example​

2.7 Performance Tips​

2.8 Error Handling​

3. API Reference​

3.1 Return Value mufftResult​

3.2 muFFT Basic Plans​

mufftPlan1d​

mufftPlan2d​

mufftPlan3d​

mufftPlanMany​

3.3 muFFT Extensible Plans​

mufftCreate​

mufftMakePlan1d​

mufftMakePlan2d​

mufftMakePlan3d​

mufftMakePlanMany​

mufftDestroy​

3.4 muFFT Plan Properties​

3.5 muFFT Estimated Size of Work Area​

mufftEstimate1d​

mufftEstimate2d​

mufftEstimate3d​

mufftEstimateMany​

3.6 muFFT Refined Estimated Size of Work Area​

mufftGetSize1d​

mufftGetSize2d​

mufftGetSize3d​

mufftGetSizeMany​

3.7 mufftGetSize()​

mufftGetSize​

3.8 muFFT Caller Allocated Work Area Support​

mufftSetWorkArea​

3.9 muFFT Execution​

mufftExecC2C​

mufftExecZ2Z​

mufftExecR2C​

mufftExecD2Z​

mufftExecC2R​

mufftExecZ2D​

3.10 muFFT and Multiple GPUs​

mufftXtSetGPUs​

mufftXtMalloc​

mufftXtFree​

mufftXtMemcpy​

mufftXtExec​

mufftXtExecDescriptor​

mufftXtExecDescriptorC2C​

mufftXtExecDescriptorZ2Z​

mufftXtExecDescriptorR2C​

mufftXtExecDescriptorD2Z​

mufftXtExecDescriptorC2R​

mufftXtExecDescriptorZ2D​

3.11 muFFT Callbacks​

mufftXtSetCallback​

mufftXtClearCallback​

3.12 mufftSetStream()​

mufftSetStream​

3.13 mufftGetVersion()​

mufftGetVersion​

3.14 mufftGetProperty()​

mufftGetProperty​

3.15 muFFT Types​

3.16 Common Types​

mufftHandle​

mufftReal​

mufftDoubleReal​

1. Introduction

1.1 What Is muFFT

1.2 Supported Transform Types

1.3 Supported Dimensions

1.4 Batch Processing

1.5 Document Scope in MUSA SDK 5.2

1.6 How to Read This Document

2. Using the muFFT API

2.1 Plan Lifecycle

2.2 Data Layout and Workspace

2.3 Stream Usage

2.4 Xt Multi-GPU Usage

2.5 Callback Usage

2.6 Examples

2.6.1 1D C2C Example

2.7 Performance Tips

2.8 Error Handling

3. API Reference

3.1 Return Value `mufftResult`

3.2 muFFT Basic Plans

`mufftPlan1d`

`mufftPlan2d`

`mufftPlan3d`

`mufftPlanMany`

3.3 muFFT Extensible Plans

`mufftCreate`

`mufftMakePlan1d`

`mufftMakePlan2d`

`mufftMakePlan3d`

`mufftMakePlanMany`

`mufftDestroy`

3.4 muFFT Plan Properties

3.5 muFFT Estimated Size of Work Area

`mufftEstimate1d`

`mufftEstimate2d`

`mufftEstimate3d`

`mufftEstimateMany`

3.6 muFFT Refined Estimated Size of Work Area

`mufftGetSize1d`

`mufftGetSize2d`

`mufftGetSize3d`

`mufftGetSizeMany`

3.7 `mufftGetSize()`

`mufftGetSize`

3.8 muFFT Caller Allocated Work Area Support

`mufftSetWorkArea`

3.9 muFFT Execution

`mufftExecC2C`

`mufftExecZ2Z`

`mufftExecR2C`

`mufftExecD2Z`

`mufftExecC2R`

`mufftExecZ2D`

3.10 muFFT and Multiple GPUs

`mufftXtSetGPUs`

`mufftXtMalloc`

`mufftXtFree`

`mufftXtMemcpy`

`mufftXtExec`

`mufftXtExecDescriptor`

`mufftXtExecDescriptorC2C`

`mufftXtExecDescriptorZ2Z`

`mufftXtExecDescriptorR2C`

`mufftXtExecDescriptorD2Z`

`mufftXtExecDescriptorC2R`

`mufftXtExecDescriptorZ2D`

3.11 muFFT Callbacks

`mufftXtSetCallback`

`mufftXtClearCallback`

3.12 `mufftSetStream()`

`mufftSetStream`

3.13 `mufftGetVersion()`

`mufftGetVersion`

3.14 `mufftGetProperty()`

`mufftGetProperty`

3.15 muFFT Types

3.16 Common Types

`mufftHandle`

`mufftReal`

`mufftDoubleReal`