A newer version of this document is available. Customers should click here to go to the newest version.
Visible to Intel only — GUID: GUID-9F4E4380-7E58-4BC6-9A65-C4C02D3AB0D3
Visible to Intel only — GUID: GUID-9F4E4380-7E58-4BC6-9A65-C4C02D3AB0D3
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); // deprecated usage, will be removed in a future release: [[deprecated("Use set_value(config_param, config_value) instead.")]] void set_value(config_param param, DFTI_CONFIG_VALUE value); [[deprecated("Use set_value(config_param, const std::vector<std::int64_t>&) instead.")]] void set_value(config_param param, const std::int64_t* value); [[deprecated("This set_value member function is deprecated.")]] void set_value(config_param param, ...); } }
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_paramenumerator), 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).
Deprecations
The configuration parameters config_param::CONJUGATE_EVEN_STORAGE, config_param::PACKED_FORMAT, config_param::COMPLEX_STORAGE, config_param::PLACEMENT and config_param::DESTROY_INPUT may also be set using the above functions. The accepted and default values correspond to the integer values explicitly assigned to the enumerators of (unscoped) enumeration type DFTI_CONFIG_VALUE that are explicitly assigned themselves to the corresponding config_value enumerators documented below for those parameters. This usage is deprecated due to the deprecation of support for DFTI_CONFIG_VALUE enumerators via the DPC++ interface of oneMKL. Using the above member function for setting any such parameter triggers a runtime deprecation warning to be emitted.
- 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::INPUT_STRIDES |
std::vector<std::int64_t> object of size |
std::vector<std::int64_t>(d+1, 0) (ignored by default due to deprecation) |
config_param::OUTPUT_STRIDES |
std::vector<std::int64_t> object of size |
std::vector<std::int64_t>(d+1, 0) (ignored by default due to deprecation) |
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 a std::vector<std::int64_t> argument containing a unique (accepted) integer value is used.
Deprecations
The usage of config_param::INPUT_STRIDES and config_param::OUTPUT_STRIDES is deprecated. More information is available in the page specific to configuring data layouts.
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::CONJUGATE_EVEN_STORAGE |
config_value::COMPLEX_COMPLEX or config_value::COMPLEX_REAL (deprecated) |
config_value::COMPLEX_COMPLEX |
config_param::PACKED_FORMAT |
config_value::CCE_FORMAT, config_value::PERM_FORMAT (deprecated), config_value::PACK_FORMAT (deprecated) or config_value::CCS_FORMAT (deprecated) |
config_value::CCE_FORMAT |
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 |
Deprecated support
The deprecated member function
template <precision prec, domain dom> void descriptor<prec, dom>::set_value(config_param param, DFTI_CONFIG_VALUE value);
offers the same support as the member function using a value of type config_value documented aboveexcept for parameters config_param::WORKSPACE (equivalent to config_param::WORKSPACE_PLACEMENT). Any call to the former is redirected internally to the latter after converting value to the corresponding config_value enumerator. Using the former function triggers a compile-time deprecation warning.
The deprecated member function
template <precision prec, domain dom> void descriptor<prec, dom>::set_value(config_param param, std::int64_t* value);
offers the same support as the member function using a value of type std::vector<std::int64_t> documented above for parameters config_param::INPUT_STRIDES, config_param::OUTPUT_STRIDES, config_param::FWD_STRIDES and config_param::BWD_STRIDES (only). Any call to the former is redirected internally to the latter after constructing the std::vector(value, value + d + 1) object (
as defined in the introduction). Using the former function triggers a compile-time deprecation warning.
The deprecated variadic member function
template <precision prec, domain dom> void descriptor<prec, dom>::set_value(config_param param, ...);
offers support for all configuration parameters. Regardless of the parameter being set, this function requires exactly two arguments and assumes a parameter-dependent type documented in the table below when reading the unique argument from the list of variadic arguments (after default argument promotions of variadic arguments, if applicable). Any call to this routine is redirected internally to the appropriate configuration-setting member function that is consistent with that assumed type of value (among those documented above, deprecated or not). Using this variadic member function triggers compile-time and runtime deprecation warnings to be emitted.
Accepted configuration parameters |
Assumed type of value |
|---|---|
config_param::FORWARD_SCALE and config_param::BACKWARD_SCALE |
double |
config_param::CONJUGATE_EVEN_STORAGE, config_param::PACKED_FORMAT, config_param::COMPLEX_STORAGE, config_param::PLACEMENT and config_param::DESTROY_INPUT |
DFTI_CONFIG_VALUE |
config_param::WORKSPACE_PLACEMENT and config_param::WORKSPACE |
config_value |
config_param::NUMBER_OF_TRANSFORMS, config_param::FWD_DISTANCE, config_param::BWD_DISTANCE and config_param::THREAD_LIMIT |
std::int64_t |
config_param::INPUT_STRIDES, config_param::OUTPUT_STRIDES, config_param::FWD_STRIDES and config_param::BWD_STRIDES |
std::int64_t* (address of the first of |
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.