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.

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 \(\left(d + 1\right)\)

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 \(\left(d + 1\right)\)

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 \(\left(d + 1\right)\)

Documented in the page specific to configuring data layouts

config_param::BWD_STRIDES

std::vector<std::int64_t> object of size \(\left(d + 1\right)\)

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

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 \(\left(d + 1\right)\) 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.