Configuration-setting member functions
This page describes the overloaded configuration-setting member functions set_value of the descriptor class template, which belongs to the oneapi::mkl::dft namespace and is declared in oneapi/mkl/dft.hpp (file to be included).
namespace oneapi::mkl::dft {
template <precision prec, domain dom>
class descriptor {
using real_scalar_t = std::conditional_t<prec == precision::DOUBLE, double, float>;
public:
// for integer-valued parameters:
void set_value(config_param param, std::int64_t value);
template <typename T, std::enable_if_t<std::is_integral_v<T>, bool> = true>
void set_value(config_param param, T value) {
set_value(param, static_cast<std::int64_t>(value));
}
// for real-valued parameters:
void set_value(config_param param, real_scalar_t value);
template <typename T, std::enable_if_t<std::is_floating_point_v<T>, bool> = true>
void set_value(config_param param, T value) {
set_value(param, static_cast<real_scalar_t>(value));
}
// for vector-valued parameters:
void set_value(config_param param, const std::vector<std::int64_t>& value);
// for other parameters:
void set_value(config_param param, config_value value);
}
}The usage of prepended namespace specifiers oneapi::mkl::dft is omitted below for conciseness.
The set_value functions enable oneMKL users to assign a configuration value to any writableconfiguration parameter of a descriptor object. In this page, the default configuration values associated with such parameters are also documented, except for parameters config_param::FWD_STRIDES and config_param::BWD_STRIDES (the reader is referred to the page dedicated to configuring data layouts for the default configuration values associated with those).
All set_value functions expect exactly two arguments: first the calling object’s configuration parameter to be set (as a config_param enumerator), second the value to be assigned to that parameter. The type of the latter depends on the parameter being set, and its acceptable values may be resricted. Note that pairs of configuration parameters and values labeled as “accepted” in tables below are not guaranteed to be unconditionally supported by descriptor objects. Configuration values may be successfully and correctly set for a descriptor object but found invalid later on, when attempting to commit that object. Assessing the validity of a descriptor object’s configuration requires knowledge (and analysis) of all its configuration values (considered “frozen” when the object is committed).
Any call to set_value resulting in a configuration change for a committeddescriptor object effectively uncommits that object: indeed, such a change typically invalidates the object’s compute-readiness preparation steps operated when it was last committed. As a consequence, any such operation changes the object’s (read-only) configuration value associated with configuration parameter config_param::COMMIT_STATUS from config_value::COMMITTED to config_value::UNCOMMITTED.
Setting integer-valued configuration parameters
The following member functions
template <precision prec, domain dom>
void descriptor<prec, dom>::set_value(config_param param, std::int64_t value);
template <precision prec, domain dom>
template <typename T, std::enable_if_t<std::is_integral_v<T>, bool> = true>
void descriptor<prec, dom>::set_value(config_param param, T value) {
set_value(param, static_cast<std::int64_t>(value));
}enable users to set configuration values for any param in the table below.
Accepted configuration parameter |
Accepted values |
Default value |
|---|---|---|
config_param::FWD_DISTANCE |
All integers |
0 |
config_param::BWD_DISTANCE |
All integers |
0 |
config_param::NUMBER_OF_TRANSFORMS |
Positive integers |
1 |
config_param::THREAD_LIMIT |
Non-negative integers |
0 |
These member functions may also be used to set any of the (real-valued) parameters config_param::FORWARD_SCALE or config_param::BACKWARD_SCALE so long as the user-provided integer value is representable as a double value without any loss of accuracy (if not, a oneapi::mkl::invalid_argument exception is thrown).
- Other integer types than std::int64_t may be used but such values must be within the representable range of std::int64_t values since the input validation operated by oneMKL is done after casting the user-provided value to std::int64_t.
Setting an integer scaling factor representable as a double without any loss of accuracy but not representable so as a float is unrecommended for single-precision descriptors as that would be responsible for truncated, possibly-incorrect results.
Setting real-valued configuration parameters
The following member functions
template <precision prec, domain dom>
void descriptor<prec, dom>::set_value(config_param param, real_scalar_t value);
template <precision prec, domain dom>
template <typename T, std::enable_if_t<std::is_floating_point_v<T>, bool> = true>
void set_value(config_param param, T value) {
set_value(param, static_cast<real_scalar_t>(value));
}enable users to set configuration values for any param in the table below.
Accepted configuration parameter |
Accepted values |
Default value |
|---|---|---|
config_param::FORWARD_SCALE |
All floating-point values |
1.0 |
config_param::BACKWARD_SCALE |
All floating-point values |
1.0 |
Setting vector-valued configuration parameters
The following member function
template <precision prec, domain dom>
void descriptor<prec, dom>::set_value(config_param param, const std::vector<std::int64_t>& value);enables users to set configuration values for any param in the table below.
Accepted configuration parameter |
Accepted values |
Default value |
|---|---|---|
config_param::FWD_STRIDES |
std::vector<std::int64_t> object of size |
Documented in the page specific to configuring data layouts |
config_param::BWD_STRIDES |
std::vector<std::int64_t> object of size |
Documented in the page specific to configuring data layouts |
The integer-valued configuration parameters listed above may also be configured using this member function, so long as an std::vector<std::int64_t> argument containing a unique (accepted) integer value is used.
Setting other configuration parameters
The following member function
template <precision prec, domain dom>
void descriptor<prec, dom>::set_value(config_param param, config_value value);enables users to set configuration values for any param in the table below.
Accepted configuration parameter |
Accepted values |
Default value |
|---|---|---|
config_param::COMPLEX_STORAGE |
config_value::COMPLEX_COMPLEX or config_value::REAL_REAL |
config_value::COMPLEX_COMPLEX |
config_param::PLACEMENT |
config_value::INPLACE or config_value::NOT_INPLACE |
config_value::INPLACE |
config_param::WORKSPACE (or config_param::WORKSPACE_PLACEMENT, equivalently) |
config_value::WORKSPACE_AUTOMATIC (equivalent to config_value::WORKSPACE_INTERNAL) or config_value::WORKSPACE_EXTERNAL |
config_value::WORKSPACE_AUTOMATIC |
config_param::DESTROY_INPUT |
config_value::AVOID or config_value::ALLOW |
config_value::AVOID |
Exceptions
The configuration-setting member functions may throw
an std::runtime_error exception if an issue is found with the calling object;
a oneapi::mkl::invalid_argument exception if
the parameter being set is not writable;
the parameter being set is rejected, e.g., if it is inconsistent with the type of configuration value being used;
the configuration value being set is rejected for the specific configuration parameter being set.
a oneapi::mkl::uninitialized exception if the calling object has been moved-from and not reinitialized.