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 writable configuration 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 committed descriptor
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 |
---|---|---|
|
All integers |
|
|
All integers |
|
|
Positive integers |
|
|
Non-negative integers |
|
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.
Note
Other integer types than
std::int64_t
may be used but such values must be within the representable range ofstd::int64_t
values since the input validation operated by oneMKL is done after casting the user-provided value tostd::int64_t
.Setting an integer scaling factor representable as a
double
without any loss of accuracy but not representable so as afloat
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 |
---|---|---|
|
All floating-point values |
|
|
All floating-point values |
|
Note
Setting a floating-point value that is not representable as a float
(resp. double
) without any loss of accuracy is unrecommended for single-precision (resp. double-precision) descriptors as that would be responsible for truncated, possibly-incorrect results.
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 |
---|---|---|
|
|
|
|
|
|
|
|
Documented in the page specific to configuring data layouts |
|
|
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 (deprecated; support for non-default values will be dropped)
|
|
|
config_param::PACKED_FORMAT (deprecated; support for non-default values will be dropped)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 above except 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 (\(d\) 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 |
---|---|
|
|
|
|
|
|
|
|
|
|
Warning
The behavior of the variadic configuration-setting member function is undefined if its usage is not strictly as documented.
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 ifthe 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.