Configuration-querying member functions#

This page describes the overloaded configuration-querying member functions get_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 the type of forward domain:
    void get_value(config_param param, domain* value_ptr) const;
    // for the floating-point format:
    void get_value(config_param param, precision* value_ptr) const;
    // for integer-valued parameters:
    void get_value(config_param param, std::int64_t* value_ptr) const;
    // for real-valued parameters:
    void get_value(config_param param, real_scalar_t* value_ptr) const;
    // for vector-valued parameters:
    void get_value(config_param param, std::vector<std::int64_t>* value_ptr) const;
    // for other parameters:
    void get_value(config_param param, config_value* value_ptr) const;
    // deprecated usage, will be removed in a future release:
    [[deprecated("Use MKL_Get_Version_String(char*, int) instead.")]]
    void get_value(config_param param, char* value_ptr) const;
    [[deprecated("Use get_value(config_param, config_value*), "
                 "get_value(config_param, domain*) or "
                 "get_value(config_param, precision*) instead.")]]
    void get_value(config_param param, DFTI_CONFIG_VALUE* value_ptr) const;
    [[deprecated("Use get_value(config_param, std::int64_t*) instead.")]]
    void get_value(config_param param, size_t* value_ptr) const;
    [[deprecated("This get_value member function is deprecated.")]]
    void get_value(config_param param, ...) const;
  }
}

The usage of prepended namespace specifiers oneapi::mkl::dft is omitted below for conciseness.

The get_value functions enable oneMKL users to query the configuration value associated with a configuration parameter of a descriptor object. All get_value functions expect exactly two arguments: first the calling object’s configuration parameter to be queried (as a config_param enumerator), second a pointer to an element (or elements) of the appropriate parameter-dependent type (documented below) wherein oneMKL is allowed to write the configuration value associated with that parameter. The calling descriptor object is left unchanged by any call to a configuration-querying member function.

Querying the type of forward domain#

The following member function

template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, domain* value_ptr) const;

enables users to query the configuration value for the configuration parameter in the table below.

Behavior of the configuration-querying member function for the type of forward domain.#

Accepted configuration parameter

Value written by oneMKL

config_param::FORWARD_DOMAIN

value_ptr[0] (assigned dom)

Querying the floating-point format#

The following member function

template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, precision* value_ptr) const;

enables users to query the configuration value for the configuration parameter in the table below.

Behavior of the configuration-querying member function for the floating-point format.#

Accepted configuration parameter

Value written by oneMKL

config_param::PRECISION

value_ptr[0] (assigned prec)

Querying integer-valued parameters#

The following member function

template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, std::int64_t* value_ptr) const;

enables users to query the configuration value for the configuration parameters in the table below.

Behavior of the configuration-querying member function for integer-valued parameters (using notations from the introduction).#

Accepted configuration parameters

Value written by oneMKL

config_param::DIMENSION, config_param::NUMBER_OF_TRANSFORMS, config_param::PLACEMENT, config_param::FWD_DISTANCE, config_param::BWD_DISTANCE, config_param::THREAD_LIMIT, config_param::WORKSPACE_ESTIMATE_BYTES, config_param::WORKSPACE_BYTES and config_param::WORKSPACE_EXTERNAL_BYTES

value_ptr[0]

config_param::FORWARD_SCALE and config_param::BACKWARD_SCALE
(See the exceptions)

value_ptr[0]

config_param::LENGTHS if \(d = 1\)

value_ptr[0] (assigned \(n_{1}\))

Deprecations#

The parameters listed in the following table had been previously accepted for querying their values as if they were integer-valued. Such usage is now deprecated in favor of safer or more-appropriately-typed alternatives (enabling proper input validation by oneMKL in case of vector-valued parameters). Querying any of the configuration parameter listed below as if it was integer-valued triggers a runtime warning to be emitted.

Behavior of the configuration-querying member function for integer-valued parameters, when used as deprecated (using notations from the introduction).#

Accepted configuration parameter(s)

Value(s) written by oneMKL

config_param::FORWARD_DOMAIN, config_param::PRECISION, config_param::COMPLEX_STORAGE, config_param::CONJUGATE_EVEN_STORAGE, config_param::PACKED_FORMAT, config_param::COMMIT_STATUS and config_param::DESTROY_INPUT

value_ptr[0]

config_param::LENGTHS if \(d > 1\)

value_ptr[0], value_ptr[1], ..., value_ptr[d-1] (assigned \(n_{1}, n_{2}, \ldots, n_{d}\), in that order)

config_param::INPUT_STRIDES, config_param::OUTPUT_STRIDES, config_param::FWD_STRIDES and config_param::BWD_STRIDES

value_ptr[0], value_ptr[1], ..., value_ptr[d] (assigned the queried \(s_{0}, s_{1}, \ldots, s_{d}\) documented in the page specific to configuring data layouts, in that order)

Querying real-valued parameters#

The following member function

template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, real_scalar_t* value_ptr) const;

enables users to query the configuration value for the configuration parameters in the table below.

Behavior of the configuration-querying member function for real-valued parameters.#

Accepted configuration parameters

Value written by oneMKL

config_param::FORWARD_SCALE and config_param::BACKWARD_SCALE

value_ptr[0]

Querying vector-valued parameters#

The following member function

template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, std::vector<std::int64_t>* value_ptr) const;

enables users to query the configuration value for the configuration parameters in the table below.

Behavior of the configuration-querying member function for vector-valued parameters (using notations from the introduction). In this table, std::int64_t* data = value_ptr->data(); is used.#

Accepted configuration parameter(s)

Value(s) written by oneMKL

Required vector size

config_param::LENGTHS

data[0], data[1], ..., data[d-1] (assigned \(n_{1}, n_{2}, \ldots, n_{d}\), in that order)

\(d\)

config_param::INPUT_STRIDES, config_param::OUTPUT_STRIDES, config_param::FWD_STRIDES and config_param::BWD_STRIDES

data[0], data[1], ..., data[d] (assigned the queried \(s_{0}, s_{1}, \ldots, s_{d}\) documented in the page specific to configuring data layouts, in that order)

\(d + 1\)

All integer-valued configuration parameter

data[0]

\(1\)

Querying other parameters#

The following member function

template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, config_value* value_ptr) const;

enables users to query the configuration value for the configuration parameters in the table below.

Behavior of the configuration-querying member function for parameters associated with config_value configuration values.#

Accepted configuration parameters

Value written by oneMKL

config_param::CONJUGATE_EVEN_STORAGE, config_param::PACKED_FORMAT, config_param::COMPLEX_STORAGE, config_param::PLACEMENT, config_param::WORKSPACE, config_param::WORKSPACE_PLACEMENT, config_param::COMMIT_STATUS, config_param::DESTROY_INPUT

value_ptr[0]

Deprecated support#

The deprecated member function

template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, size_t* value_ptr) const;

offers the same support as the member function using a value_ptr of type std::int64_t* documented above. Using the former function triggers a compile-time deprecation warning.

The deprecated member function

template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, DFTI_CONFIG_VALUE* value_ptr) const;

enables users to query the configuration value for the configuration parameters in the table below, using the oneMKL C interface’s DFTI_CONFIG_VALUE enumerators that are now deprecated via the oneMKL DPC++ interface. Using this function triggers a compile-time deprecation warning.

Behavior of the configuration-querying member function for parameters associatable with a configuration value of type DFTI_CONFIG_VALUE (deprecated).#

Accepted configuration parameters

Value written by oneMKL

config_param::CONJUGATE_EVEN_STORAGE, config_param::PACKED_FORMAT, config_param::FORWARD_DOMAIN, config_param::PRECISION, config_param::COMPLEX_STORAGE, config_param::PLACEMENT, config_param::COMMIT_STATUS and config_param::DESTROY_INPUT

value_ptr[0]

The deprecated member function

template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, char* value_ptr) const;

serves no other purpose than querying textual information about the version of oneMKL being used. The very same information may be obtained via MKL_Get_Version_String (declared in mkl_service.h).

Behavior of the configuration-querying member function for the only parameter associatable with a C-style string (deprecated).#

Accepted configuration parameter

Range of values possibly written by oneMKL

config_param::VERSION

from value_ptr[0] to value_ptr[DFTI_VERSION_LENGTH-1] (DFTI_VERSION_LENGTH defined in mkl_dfti.h)

The deprecated variadic member function

template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, ...) const;

offers support for all configuration parameters. Regardless of the parameter being queried, this function requires exactly two arguments and assumes a parameter-dependent pointer 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-querying member function that is consistent with that assumed pointer 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 pointer type considered by the variadic configuration-querying member function when reading its second argument, i.e., the first in the list of variadic arguments.#

Accepted configuration parameter(s)

Assumed pointer type

config_param::DIMENSION, config_param::NUMBER_OF_TRANSFORMS, config_param::FWD_DISTANCE, config_param::BWD_DISTANCE, config_param::THREAD_LIMIT, config_param::LENGTHS, config_param::INPUT_STRIDES, config_param::OUTPUT_STRIDES, config_param::FWD_STRIDES and config_param::BWD_STRIDES

std::int64_t*

config_param::WORKSPACE_ESTIMATE_BYTES, config_param::WORKSPACE_BYTES and config_param::WORKSPACE_EXTERNAL_BYTES

size_t*

config_param::FORWARD_SCALE and config_param::BACKWARD_SCALE

float* (resp. double*) for single-precision (resp. double-precision) descriptors

config_param::WORKSPACE and config_param::WORKSPACE_PLACEMENT

config_value*

config_param::FORWARD_DOMAIN, config_param::PRECISION, config_param::COMPLEX_STORAGE, config_param::CONJUGATE_EVEN_STORAGE, config_param::PACKED_FORMAT, config_param::PLACEMENT, config_param::COMMIT_STATUS, config_param::DESTROY_INPUT

DFTI_CONFIG_VALUE*

config_param::VERSION

char*

Warning

The behavior of the variadic configuration-querying member function is undefined if its usage is not strictly as documented.

Exceptions#

The configuration-querying member functions may throw

  • an std::runtime_error exception if an issue is found with the calling object;

  • a oneapi::mkl::uninitialized exception if the calling object is uncommitted yet queried about a configuration parameter that requires the calling object to be committed (e.g., config_param::WORKSPACE_BYTES or WORKSPACE_EXTERNAL_BYTES);

  • a oneapi::mkl::unimplemented exception if the queried parameter corresponds to a feature that is not implemented for the calling object (e.g., config_param::WORKSPACE_BYTES or WORKSPACE_EXTERNAL_BYTES for a CPU-committed descriptor);

  • a oneapi::mkl::invalid_argument exception if

    • the second argument is nullptr;

    • the parameter being queried is rejected, e.g., if it is inconsistent with the pointer type used as second argument;

    • the size of the vector pointed by value_ptr is not as required, for vector-valued-parameters;

    • the configuration value to be returned cannot be safely or accurately converted into the desired type, e.g., if querying a scaling factor that happens to be \(0.5\) using the configuration-querying member function specific to integer-valued configuration parameters.