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
-
SPFFT_EXPORT 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)
Creates a transform from a grid handle.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[out] transform
: Handle to the transform.[in] grid
: Handle to the grid, with which the transform is created.[in] processingUnit
: The processing unit type to use. Must be either SPFFT_PU_HOST or SPFFT_PU_GPU and be supported by the grid itself.[in] transformType
: The transform type (complex to complex or real to complex). Can be SPFFT_TRANS_C2C or SPFFT_TRANS_R2C.[in] dimX
: The dimension in x. The maximum allowed depends on the grid parameters.[in] dimY
: The dimension in y. The maximum allowed depends on the grid parameters.[in] dimZ
: The dimension in z. The maximum allowed depends on the grid parameters.[in] localZLength
: The length in z in space domain of the local MPI rank.[in] numLocalElements
: The number of elements in frequency domain of the local MPI rank.[in] indexFormat
: The index format. Only SPFFT_INDEX_TRIPLETS currently supported.[in] indices
: Pointer to the frequency indices. Posive and negative indexing is supported.
-
SPFFT_EXPORT SpfftError spfft_transform_destroy(SpfftTransform transform)
Destroy a transform.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.
-
SPFFT_EXPORT SpfftError spfft_transform_clone(SpfftTransform transform, SpfftTransform * newTransform)
Clone a transform.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[out] newTransform
: Independent transform with the same parameters, but with new underlying grid.
-
SPFFT_EXPORT SpfftError spfft_transform_forward(SpfftTransform transform, SpfftProcessingUnitType inputLocation, double * output, SpfftScalingType scaling)
Execute a forward transform from space domain to frequency domain.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[in] inputLocation
: The processing unit, to take the input from. Can be SPFFT_PU_HOST or SPFFT_PU_GPU (if GPU is set as execution unit).[out] output
: 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).[in] scaling
: Controls scaling of output. SPFFT_NO_SCALING to disable or SPFFT_FULL_SCALING to scale by factor 1 / (dim_x() * dim_y() * dim_z()).
-
SPFFT_EXPORT SpfftError spfft_transform_backward(SpfftTransform transform, const double * input, SpfftProcessingUnitType outputLocation)
Execute a backward transform from frequency domain to space domain.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[in] input
: 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.[in] outputLocation
: The processing unit, to place the output at. Can be SPFFT_PU_HOST or SPFFT_PU_GPU (if GPU is set as execution unit).
-
SPFFT_EXPORT SpfftError spfft_transform_get_space_domain(SpfftTransform transform, SpfftProcessingUnitType dataLocation, double ** data)
Provides access to the space domain data.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[in] dataLocation
: The processing unit to query for the data. Can be SPFFT_PU_HOST or SPFFT_PU_GPU (if GPU is set as execution unit).[out] data
: Pointer to space domain data on given processing unit. Alignment is guaranteed to fulfill requirements for std::complex and C language complex types.
- Exceptions
GenericError
: SpFFT error. Can be a derived type.std::exception
: Error from standard library calls. Can be a derived type.
-
SPFFT_EXPORT SpfftError spfft_transform_dim_x(SpfftTransform transform, int * dimX)
Access a transform parameter.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[out] dimX
: Dimension in x.
-
SPFFT_EXPORT SpfftError spfft_transform_dim_y(SpfftTransform transform, int * dimY)
Access a transform parameter.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[out] dimY
: Dimension in y.
-
SPFFT_EXPORT SpfftError spfft_transform_dim_z(SpfftTransform transform, int * dimZ)
Access a transform parameter.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[out] dimZ
: Dimension in z.
-
SPFFT_EXPORT SpfftError spfft_transform_local_z_length(SpfftTransform transform, int * localZLength)
Access a transform parameter.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[out] localZLength
: size in z of the slice in space domain on the local MPI rank.
-
SPFFT_EXPORT SpfftError spfft_transform_local_slice_size(SpfftTransform transform, int * size)
Access a transform parameter.
- Parameters
[in] transform
: Handle to the transform.[out] size
: Number of elements in the space domain slice held by the local MPI rank.
-
SPFFT_EXPORT SpfftError spfft_transform_local_z_offset(SpfftTransform transform, int * offset)
Access a transform parameter.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[out] offset
: Offset in z of the space domain slice held by the local MPI rank.
-
SPFFT_EXPORT SpfftError spfft_transform_global_size(SpfftTransform transform, long long int * globalSize)
Access a transform parameter.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[out] globalSize
: Global number of elements in space domain. Equals dim_x() * dim_y() * dim_z().
-
SPFFT_EXPORT SpfftError spfft_transform_num_local_elements(SpfftTransform transform, int * numLocalElements)
Access a transform parameter.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[out] numLocalElements
: Number of local elements in frequency domain.
-
SPFFT_EXPORT SpfftError spfft_transform_num_global_elements(SpfftTransform transform, long long int * numGlobalElements)
Access a transform parameter.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[out] numGlobalElements
: Global number of elements in space domain. Equals dim_x() * dim_y()dim_z().
-
SPFFT_EXPORT SpfftError spfft_transform_device_id(SpfftTransform transform, int * deviceId)
Access a transform parameter.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[out] deviceId
: The GPU device id used. Returns always 0, if no GPU support is enabled.
-
SPFFT_EXPORT SpfftError spfft_transform_num_threads(SpfftTransform transform, int * numThreads)
Access a transform parameter.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[out] numThreads
: 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.
-
SPFFT_EXPORT SpfftError spfft_transform_communicator(SpfftTransform transform, MPI_Comm * comm)
Access a transform parameter.
- Return
Error code or SPFFT_SUCCESS.
- Parameters
[in] transform
: Handle to the transform.[out] comm
: The internal MPI communicator.