A newer version of this document is available. Customers should click here to go to the newest version.
Visible to Intel only — GUID: GUID-A46794D3-2293-4FD3-BD5E-EFDABCF9D92B
Visible to Intel only — GUID: GUID-A46794D3-2293-4FD3-BD5E-EFDABCF9D92B
descriptor<precision, domain>::set_value
Sets one configuration parameter with the specified configuration value. This routine belongs to the oneapi::mkl::dft namespace.
Description
This function sets one configuration parameter with the specified configuration value and throws an std::runtime_exception in the case that it fails. Each configuration parameter is a named constant, and the configuration value must have the corresponding type, which can be a named constant or a native type. The DPC++ configuration parameters have type mkl::dft::config_param. Each parameter mkl::dft::config_param::<PARAMETER_NAME> has the same meaning and possible values as the C interface’s DFTI_<PARAMETER_NAME>. Some of the options available in the C interface are not fully supported in the DPC++ interface yet. See the note below and the Intel® oneAPI Math Kernel Library Release Notes. For a full description of each parameter’s meaning and options, see Config Params.
- An important difference in the configuration options for DPC++ FFT interface is the use of FWD_DISTANCE and BWD_DISTANCE instead of INPUT_DISTANCE and OUTPUT_DISTANCE. The FWD_DISTANCE describes the number of elements between different batched FFTs for the forward domain while BWD_DISTANCE describes the number of elements between different batched FFTs for the backward domain. This allows a committed descriptor to compute both forward and backward transforms without resetting the distance parameters. It is required for all R2C or C2R transforms to use FWD_DISTANCE and BWD_DISTANCE instead of INPUT_DISTANCE and OUTPUT_DISTANCE.
For COMPLEX_STORAGE, only the DFTI_COMPLEX_COMPLEX format is currently supported on CPU and GPU devices.
For batched 3D C2C problems, only FWD_DISTANCE or BWD_DISTANCE equal to the problem size are supported currently.
In the case of a real forward domain, the only supported values on GPU devices for CONJUGATE_EVEN_STORAGE and PACKED_FORMAT are respectively DFTI_COMPLEX_COMPLEX and DFTI_CCE_FORMAT. These values are set by default and require the setting of the INPUT_STRIDE and OUTPUT_STRIDE parameters before calling commit. (While these default values differ from the current C interface defaults, the C default values will be brought into alignment with these default values following the full deprecation process of the current C default values. See the deprecation notice at DFTI_COMPLEX_STORAGE, DFTI_REAL_STORAGE, DFTI_CONJUGATE_EVEN_STORAGE.)
In the case of a real forward domain, arbitrary strides and batch distances are not supported for multi-dimensional transforms on GPU. Considering the last dimension of the data, every element must be separated from its nearest peer(s) (along another dimension and/or in another batch) by a constant distance. For example, to compute a batched, two-dimensional R2C FFT of size [N2, N1] with input strides [0, S2, 1] (row-major layout with unit elementary stride and no offset), FWD_DISTANCE must be equal to N2*S2 so that every element is separated from its nearest last-dimension counterpart(s) by a distance S2 (in this example), even across batches.
Transforms on GPU devices may overwrite FFT-irrelevant, padding entries in the output data.
The set_value function cannot be used to change configuration parameters mkl::dft::config_param::FORWARD_DOMAIN, mkl::dft::config_param::PRECISION since these are a part of the template. Likewise, mkl::dft::config_param::LENGTHS is set with the constructor.
All calls to set_value() must be done before calls to commit(). This is because the handle may have been moved to an offloaded device after commit().
Function calls needed to configure an FFT descriptor for a particular call to an FFT computation function are summarized in Configuring and Computing an FFT in C/C++.
API
Syntax
namespace oneapi::mkl::dft{
void descriptor<prec,dom>::set_value(config_param param, ...);
}
Include Files
oneapi/mkl/dfti.hpp
Input Parameters
Name |
Type |
Description |
|---|---|---|
param |
mkl::dft::config_param |
Configuration parameter |
value |
Depends on the configuration parameter |
Configuration value |