Transform

Note

This class only holds an internal reference counted object. The object remains in a usable state even if the associated Grid object is destroyed. In addition, copying a transform only requires an internal copy of a shared pointer.

Typedefs

typedef void *SpfftTransform: Transform handle.

Functions

SpfftError spfft_transform_create(SpfftTransform *transform, SpfftGrid grid, SpfftProcessingUnitType processingUnit, SpfftTransformType transformType, int dimX, int dimY, int dimZ, int localZLength, int numLocalElements, SpfftIndexFormatType indexFormat, const int *indices)

Create a transform from a grid handle.

Thread-safe if no FFTW calls are executed concurrently.

Parameters:

transform – [out] Handle to the transform.
grid – [in] Handle to the grid, with which the transform is created.
processingUnit – [in] The processing unit type to use. Must be either SPFFT_PU_HOST or SPFFT_PU_GPU and be supported by the grid itself.
transformType – [in] The transform type (complex to complex or real to complex). Can be SPFFT_TRANS_C2C or SPFFT_TRANS_R2C.
dimX – [in] The dimension in x. The maximum allowed depends on the grid parameters.
dimY – [in] The dimension in y. The maximum allowed depends on the grid parameters.
dimZ – [in] The dimension in z. The maximum allowed depends on the grid parameters.
localZLength – [in] The length in z in space domain of the local MPI rank.
numLocalElements – [in] The number of elements in frequency domain of the local MPI rank.
indexFormat – [in] The index format. Only SPFFT_INDEX_TRIPLETS currently supported.
indices – [in] Pointer to the frequency indices. Centered indexing is allowed.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_create_independent(SpfftTransform *transform, int maxNumThreads, SpfftProcessingUnitType processingUnit, SpfftTransformType transformType, int dimX, int dimY, int dimZ, int numLocalElements, SpfftIndexFormatType indexFormat, const int *indices)

Create a transform without a grid handle.

Thread-safe if no FFTW calls are executed concurrently.

Parameters:

transform – [out] Handle to the transform.
maxNumThreads – [in] The maximum number of threads to use.
processingUnit – [in] The processing unit type to use. Must be either SPFFT_PU_HOST or SPFFT_PU_GPU.
transformType – [in] The transform type (complex to complex or real to complex). Can be SPFFT_TRANS_C2C or SPFFT_TRANS_R2C.
dimX – [in] The dimension in x.
dimY – [in] The dimension in y.
dimZ – [in] The dimension in z.
numLocalElements – [in] The number of elements in frequency domain.
indexFormat – [in] The index format. Only SPFFT_INDEX_TRIPLETS currently supported.
indices – [in] Pointer to frequency indices. Centered indexing is allowed.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_create_independent_distributed(SpfftTransform *transform, int maxNumThreads, MPI_Comm comm, SpfftExchangeType exchangeType, SpfftProcessingUnitType processingUnit, SpfftTransformType transformType, int dimX, int dimY, int dimZ, int localZLength, int numLocalElements, SpfftIndexFormatType indexFormat, const int *indices)

Create a distributed transform without a grid handle.

Thread-safe if no FFTW calls are executed concurrently.

Parameters:

transform – [out] Handle to the transform.
maxNumThreads – [in] The maximum number of threads to use.
comm – [in] The MPI communicator to use. Will be duplicated for internal use.
exchangeType – [in] The type of MPI exchange to use. Possible values are SPFFT_EXCH_DEFAULT, SPFFT_EXCH_BUFFERED, SPFFT_EXCH_COMPACT_BUFFERED and SPFFT_EXCH_UNBUFFERED.
processingUnit – [in] The processing unit type to use. Must be either SPFFT_PU_HOST or SPFFT_PU_GPU.
transformType – [in] The transform type (complex to complex or real to complex). Can be SPFFT_TRANS_C2C or SPFFT_TRANS_R2C.
dimX – [in] The dimension in x.
dimY – [in] The dimension in y.
dimZ – [in] The dimension in z.
localZLength – [in] The length in z in space domain of the local MPI rank.
numLocalElements – [in] The number of elements in frequency domain of the local MPI rank.
indexFormat – [in] The index format. Only SPFFT_INDEX_TRIPLETS currently supported.
indices – [in] Pointer to frequency indices. Centered indexing is allowed.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_destroy(SpfftTransform transform)

Destroy a transform.

Parameters:: transform – [in] Handle to the transform.
Returns:: Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_clone(SpfftTransform transform, SpfftTransform *newTransform)

Clone a transform.

Parameters:

transform – [in] Handle to the transform.
newTransform – [out] Independent transform with the same parameters, but with new underlying grid.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_forward(SpfftTransform transform, SpfftProcessingUnitType inputLocation, double *output, SpfftScalingType scaling)

Execute a forward transform from space domain to frequency domain.

Parameters:

transform – [in] Handle to the transform.
inputLocation – [in] The processing unit, to take the input from. Can be SPFFT_PU_HOST or SPFFT_PU_GPU (if GPU is set as execution unit).
output – [out] Pointer to memory, where the frequency domain elements are written to. Can be located at Host or GPU memory (if GPU is set as processing unit).
scaling – [in] Controls scaling of output. SPFFT_NO_SCALING to disable or SPFFT_FULL_SCALING to scale by factor 1 / (dim_x() * dim_y() * dim_z()).

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_forward_ptr(SpfftTransform transform, const double *input, double *output, SpfftScalingType scaling)

Execute a forward transform from space domain to frequency domain.

Parameters:

transform – [in] Handle to the transform.
input – [in] Pointer to memory, to read space domain data from. Can be located at Host or GPU memory (if GPU is set as processing unit).
output – [out] Pointer to memory, where the frequency domain elements are written to. Can be located at Host or GPU memory (if GPU is set as processing unit).
scaling – [in] Controls scaling of output. SPFFT_NO_SCALING to disable or SPFFT_FULL_SCALING to scale by factor 1 / (dim_x() * dim_y() * dim_z()).

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_backward(SpfftTransform transform, const double *input, SpfftProcessingUnitType outputLocation)

Execute a backward transform from frequency domain to space domain.

Parameters:

transform – [in] Handle to the transform.
input – [in] Input data in frequency domain. Must match the indices provided at transform creation. Can be located at Host or GPU memory, if GPU is set as processing unit.
outputLocation – [in] The processing unit, to place the output at. Can be SPFFT_PU_HOST or SPFFT_PU_GPU (if GPU is set as execution unit).

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_backward_ptr(SpfftTransform transform, const double *input, double *output)

Execute a backward transform from frequency domain to space domain.

Parameters:

transform – [in] Handle to the transform.
input – [in] Input data in frequency domain. Must match the indices provided at transform
output – [out] Pointer to memory to write output in frequency domain to. Can be located at Host or GPU memory, if GPU is set as processing unit. creation. Can be located at Host or GPU memory, if GPU is set as processing unit.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_get_space_domain(SpfftTransform transform, SpfftProcessingUnitType dataLocation, double **data)

Provides access to the space domain data.

Parameters:

transform – [in] Handle to the transform.
dataLocation – [in] The processing unit to query for the data. Can be SPFFT_PU_HOST or SPFFT_PU_GPU (if GPU is set as execution unit).
data – [out] Pointer to space domain data on given processing unit. Alignment is guaranteed to fulfill requirements for std::complex and C language complex types.

Throws:

GenericError – SpFFT error. Can be a derived type.
std::exception – Error from standard library calls. Can be a derived type.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_dim_x(SpfftTransform transform, int *dimX)

Access a transform parameter.

Parameters:

transform – [in] Handle to the transform.
dimX – [out] Dimension in x.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_dim_y(SpfftTransform transform, int *dimY)

Access a transform parameter.

Parameters:

transform – [in] Handle to the transform.
dimY – [out] Dimension in y.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_dim_z(SpfftTransform transform, int *dimZ)

Access a transform parameter.

Parameters:

transform – [in] Handle to the transform.
dimZ – [out] Dimension in z.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_local_z_length(SpfftTransform transform, int *localZLength)

Access a transform parameter.

Parameters:

transform – [in] Handle to the transform.
localZLength – [out] size in z of the slice in space domain on the local MPI rank.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_local_slice_size(SpfftTransform transform, int *size)

Access a transform parameter.

Parameters:

transform – [in] Handle to the transform.
size – [out] Number of elements in the space domain slice held by the local MPI rank.

SpfftError spfft_transform_local_z_offset(SpfftTransform transform, int *offset)

Access a transform parameter.

Parameters:

transform – [in] Handle to the transform.
offset – [out] Offset in z of the space domain slice held by the local MPI rank.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_global_size(SpfftTransform transform, long long int *globalSize)

Access a transform parameter.

Parameters:

transform – [in] Handle to the transform.
globalSize – [out] Global number of elements in space domain. Equals dim_x() * dim_y() * dim_z().

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_num_local_elements(SpfftTransform transform, int *numLocalElements)

Access a transform parameter.

Parameters:

transform – [in] Handle to the transform.
numLocalElements – [out] Number of local elements in frequency domain.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_num_global_elements(SpfftTransform transform, long long int *numGlobalElements)

Access a transform parameter.

Parameters:

transform – [in] Handle to the transform.
numGlobalElements – [out] Global number of elements in space domain. Equals dim_x() * dim_y()
- dim_z().

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_device_id(SpfftTransform transform, int *deviceId)

Access a transform parameter.

Parameters:

transform – [in] Handle to the transform.
deviceId – [out] The GPU device id used. Returns always 0, if no GPU support is enabled.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_num_threads(SpfftTransform transform, int *numThreads)

Access a transform parameter.

Parameters:

transform – [in] Handle to the transform.
numThreads – [out] The exact number of threads used by transforms created from this grid. May be less than the maximum given to the constructor. Always 1, if not compiled with OpenMP support.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_execution_mode(SpfftTransform transform, SpfftExecType *mode)

Access a transform parameter.

Parameters:

transform – [in] Handle to the transform.
mode – [out] The execution mode. Only affects execution on GPU. Defaults to SPFFT_EXEC_SYNCHRONOUS.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_set_execution_mode(SpfftTransform transform, SpfftExecType mode)

Set a transform parameter.

Parameters:

transform – [in] Handle to the transform.
[int] – mode The execution mode to change to. Only affects execution on GPU. Defaults to SPFFT_EXEC_SYNCHRONOUS.

Returns:

Error code or SPFFT_SUCCESS.

SpfftError spfft_transform_communicator(SpfftTransform transform, MPI_Comm *comm)

Access a transform parameter.

Parameters:

transform – [in] Handle to the transform.
comm – [out] The internal MPI communicator.

Returns:

Error code or SPFFT_SUCCESS.