Configuration-setting member functions

oneMKL - Data Parallel C++ Developer Reference

Download PDF

ID 772045

Date 6/24/2024

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-9F4E4380-7E58-4BC6-9A65-C4C02D3AB0D3

View Details

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.

Integer-valued configuration parameters along with their accepted and default values.
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.

NOTE:

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.

Real-valued configuration parameters along with their accepted and default values.
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`

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.

Vector-valued configuration parameters along with their accepted and default values (using notations from the introduction).

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.

Configuration parameters associated with configuration values in `config_value` along with their accepted and default values.
Accepted configuration parameter	Accepted values	Default value
`config_param::CONJUGATE_EVEN_STORAGE` (deprecated; support for non-default values will be dropped)	`config_value::COMPLEX_COMPLEX` or `config_value::COMPLEX_REAL` (deprecated)	`config_value::COMPLEX_COMPLEX`
`config_param::PACKED_FORMAT` (deprecated; support for non-default values will be dropped)	`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.

Assumed type of value considered by the variadic configuration-setting member function when reading its second argument, i.e., the first in the list of variadic arguments (using notations from the introduction).

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 contiguous `std::int64_t` values)

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 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.

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

oneMKL - Data Parallel C++ Developer Reference

Configuration-setting member functions

Setting integer-valued configuration parameters

Setting real-valued configuration parameters

Setting vector-valued configuration parameters

Setting other configuration parameters

Deprecated support

Exceptions