User-Allocated Workspaces

oneMKL - Data Parallel C++ Developer Reference

Download PDF

ID 772045

Date 11/07/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-20F08182-9CA4-494C-9392-BC5F20136285

View Details

User-Allocated Workspaces

During the FFT execution, the descriptor object may require additional memory to store intermediate results or pre-computed data. By default, the descriptor allocates this workspace internally. oneMKL DFT provides a combination of existing and new APIs to enable the user to manage this workspace.

NOTE:

User-allocated workspaces are currently supported only for GPU devices.

User’s intention regarding workspace
Get workspace estimate
Get the exact workspace size
Provide the workspace to the descriptor

User’s intention regarding workspace

The descriptor allocates any required workspace internally during the commit by default. The following needs to be set before commit to let oneMKL DFT know that the workspace will be provided by the user.

descriptor.set_value(oneapi::mkl::dft::config_param::WORKSPACE, oneapi::mkl::dft::config_value::WORKSPACE_EXTERNAL);

The above call will notify the descriptor to not allocate any internal workspace during the commit.

NOTE:

If the user did not notify the descriptor before commit that an external workspace will be provided, they can directly call set_workspace, which will override the internal allocations and utilize the user-workspace.

Get workspace estimate

The below optional call to get_value before the commit provides a conservative estimate of the workspace size that may be required.

size_t workspaceEstimate = 0;
descriptor.get_value(oneapi::mkl::dft::config_param::WORKSPACE_ESTIMATE, &workspaceEstimate);

The estimate in bytes will be stored in the workspaceEstimate variable.

NOTE:

The workspace estimate values pertain to GPU devices only.

Get the exact workspace size

The below call to get_value returns the exact amount of workspace size that will be required by the descriptor for computing the FFT. This needs to be called after the commit.

size_t workspaceSize = 0;
descriptor.get_value(oneapi::mkl::dft::config_param::WORKSPACE_BYTES, &workspaceSize);

The workspace size in bytes will be stored in the workspaceSize variable.

NOTE:

Trying to get the exact workspace size before commit will throw a std::runtime_exception().

Provide the workspace to the descriptor

The below descriptor class member functions will enable the user to set/replace the workspace either in the form of SYCL buffer or device-accessible USM. If the workspace was internally allocated (config_param::WORKSPACE was not set to config_value::WORKSPACE_EXTERNAL before commit), setting the workspace will deallocate any internal workspace and user-provided workspace will be used.

Syntax

namespace oneapi::mkl::dft{
  void descriptor<prec, dom>::set_workspace<data_type>(sycl::buffer<data_type, 1> &workspaceBuf);
  void descriptor<prec, dom>::set_workspace<data_type>(data_type *workspaceUsm);
}

NOTE:

The descriptor assumes that the workspace will be solely used for FFT, so the user must be careful not to use the same workspace area for other purposes in parallel or before finishing compute_forward/compute_backward (especially for USM as explicit synchronization is required).
In case of USM, it is assumed that the workspace is large enough. In case of Buffer, std::runtime_exception() will be thrown if the workspace size is smaller than required.
If the user calls compute_forward or compute_backward before setting the workspace a std::runtime_exception() will be thrown.
Currently, the workspace type (Buffer or USM) must be the same as the container type(Buffer or USM) used during the compute stage. Otherwise, std::runtime_exception() will be thrown.
Sub-buffer workspaces are not supported and may result in runtime errors.

Include Files

oneapi/mkl/dfti.hpp

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

oneMKL - Data Parallel C++ Developer Reference

User-Allocated Workspaces

User’s intention regarding workspace

Get workspace estimate

Get the exact workspace size

Provide the workspace to the descriptor