Scoped enumerations

Scoped enumerations#

This page describes the scoped enumerations pertaining to the definition or configuration of oneapi::mkl::dft::descriptor objects: oneapi::mkl::dft::precision, oneapi::mkl::dft::domain, oneapi::mkl::dft::config_param, and oneapi::mkl::dft::config_value.

namespace oneapi::mkl::dft {
  enum class precision {
    SINGLE = DFTI_SINGLE,
    DOUBLE = DFTI_DOUBLE
  };

  enum class domain {
     REAL    = DFTI_REAL,
     COMPLEX = DFTI_COMPLEX
  };

  enum class config_param {
     FORWARD_DOMAIN                          = DFTI_FORWARD_DOMAIN,
     DIMENSION                               = DFTI_DIMENSION,
     LENGTHS                                 = DFTI_LENGTHS,
     PRECISION                               = DFTI_PRECISION,
     FORWARD_SCALE                           = DFTI_FORWARD_SCALE,
     BACKWARD_SCALE                          = DFTI_BACKWARD_SCALE,
     NUMBER_OF_TRANSFORMS                    = DFTI_NUMBER_OF_TRANSFORMS,
     COMPLEX_STORAGE                         = DFTI_COMPLEX_STORAGE,
     CONJUGATE_EVEN_STORAGE  [[deprecated]]  = DFTI_CONJUGATE_EVEN_STORAGE,
     PLACEMENT                               = DFTI_PLACEMENT,
     INPUT_STRIDES           [[deprecated("Use FWD/BWD strides instead.")]]
                                             = DFTI_INPUT_STRIDES,
     OUTPUT_STRIDES          [[deprecated("Use FWD/BWD strides instead.")]]
                                             = DFTI_OUTPUT_STRIDES,
     FWD_DISTANCE                            = DFTI_FWD_DISTANCE,
     BWD_DISTANCE                            = DFTI_BWD_DISTANCE,
     WORKSPACE                               = DFTI_WORKSPACE,
     PACKED_FORMAT           [[deprecated]]  = DFTI_PACKED_FORMAT,
     COMMIT_STATUS                           = DFTI_COMMIT_STATUS,
     VERSION                 [[deprecated]]  = DFTI_VERSION,
     THREAD_LIMIT                            = DFTI_THREAD_LIMIT,
     DESTROY_INPUT                           = DFTI_DESTROY_INPUT,
     WORKSPACE_ESTIMATE_BYTES,
     WORKSPACE_BYTES,
     FWD_STRIDES,
     BWD_STRIDES,
     WORKSPACE_PLACEMENT,        // alias for WORKSPACE
     WORKSPACE_EXTERNAL_BYTES    // alias for WORKSPACE_BYTES
  };

  enum class config_value {
     COMMITTED                               = DFTI_COMMITTED,
     UNCOMMITTED                             = DFTI_UNCOMMITTED,
     COMPLEX_COMPLEX                         = DFTI_COMPLEX_COMPLEX,
     REAL_REAL                               = DFTI_REAL_REAL,
     INPLACE                                 = DFTI_INPLACE,
     NOT_INPLACE                             = DFTI_NOT_INPLACE,
     WORKSPACE_AUTOMATIC,        // alias for WORKSPACE_INTERNAL
     COMPLEX_REAL            [[deprecated]]  = DFTI_COMPLEX_REAL,
     ALLOW                                   = DFTI_ALLOW,
     AVOID                                   = DFTI_AVOID,
     CCE_FORMAT              [[deprecated]]  = DFTI_CCE_FORMAT,
     PERM_FORMAT             [[deprecated]]  = DFTI_PERM_FORMAT,
     PACK_FORMAT             [[deprecated]]  = DFTI_PACK_FORMAT,
     CCS_FORMAT              [[deprecated]]  = DFTI_CCS_FORMAT,
     WORKSPACE_INTERNAL,
     WORKSPACE_EXTERNAL
  };
}

These scoped enumerations belong to the oneapi::mkl::dft namespace and are declared in oneapi/mkl/dft.hpp (file to be included). The usage of prepended namespace specifiers oneapi::mkl::dft is omitted below for conciseness.

All configuration parameters of oneMKL descriptor objects are captured by an enumerator in config_param and associated with a configuration value. When the latter is not representable with a primitive or derived data type, it is representable with an enumerator in domain, precision or config_value.

The default configuration values associated with all writable configuration parameters are documented in the page dedicated to the configuration-setting member function(s) of the descriptor class template, or in the page specific to configuring data layouts.

config_param#

This scoped enumeration type is used to represent all configuration parameters of oneMKL DFT descriptor objects. For any descriptor object, all its configuration parameters are associated with a configuration value. The type of the latter depends on the configuration parameter and is documented in the page specific to the configuration-setting (or configuration-querying, for read-only parameters) member functions of the descriptor class template.

Enumerators of the config_param scoped enumeration along with the corresponding configuration parameters of descriptor objects. The table uses the notations and mathematical symbols presented in the introduction when referring to parameters of the DFT operation defined by the object.#

Enumerator(s)

Corresponding configuration parameter.

config_param::FORWARD_DOMAIN

Type of forward domain for the DFT.

config_param::DIMENSION

Dimension \(d\) of the DFT.

config_param::LENGTHS

Length(s) \(\lbrace n_1, n_2, \ldots, n_d\rbrace\) of the DFT.

config_param::PRECISION

Floating-point format for the DFT.

config_param::FORWARD_SCALE

Scaling factor of the forward DFT, i.e., \(\sigma_{-1}\).

config_param::BACKWARD_SCALE

Scaling factor of the backward DFT, i.e., \(\sigma_{+1}\).

config_param::NUMBER_OF_TRANSFORMS

Batch size \(M\) of the DFT.

config_param::PLACEMENT

Configuration parameter indicating whether the DFT computation is performed in-place or not. The interested reader is referred to the page specific to configuring the placement of the DFT results for more details.

config_param::COMPLEX_STORAGE

Elementary data type to be considered in either domain by a complex descriptor (irrelevant parameter for real descriptors). The interested reader is referred to the page specific to configuring data layouts for more details.

config_param::CONJUGATE_EVEN_STORAGE

Elementary data type to be considered in the backward domain by a real descriptor (irrelevant parameter for complex descriptors). The interested reader is referred to the page specific to configuring data layouts for more details.
This parameter is deprecated (support for non-default values will be dropped).

config_param::INPUT_STRIDES

Index offset and strides to be considered when accessing entries in the relevant input data container provided by the user. The interested reader is referred to the page specific to configuring data layouts for more details.
This parameter is deprecated; it is recommended to use config_param::FWD_STRIDES and config_param::BWD_STRIDES instead.

config_param::OUTPUT_STRIDES

Index offset and strides to be considered when accessing entries in the relevant output data container provided by the user. The interested reader is referred to the page specific to configuring data layouts for more details.
This parameter is deprecated; it is recommended to use config_param::FWD_STRIDES and config_param::BWD_STRIDES instead.

config_param::FWD_STRIDES

Index offset and strides to be considered when accessing entries in the forward domain’s data container provided by the user. The interested reader is referred to the page specific to configuring data layouts for more details.

config_param::BWD_STRIDES

Index offset and strides to be considered when accessing entries in the backward domain’s data container provided by the user. The interested reader is referred to the page specific to configuring data layouts for more details.

config_param::FWD_DISTANCE

Distance to be considered when accessing entries in the forward domain’s data container provided by the user. The interested reader is referred to the page specific to configuring data layouts for more details.

config_param::BWD_DISTANCE

Distance to be considered when accessing entries in the backward domain’s data container provided by the user. The interested reader is referred to the page specific to configuring data layouts for more details.

config_param::PACKED_FORMAT

Data storage convention to be used in the backward domain of real descriptors (irrelevant for complex descriptors). The interested reader is referred to the page specific to configuring data layouts for more details.
This parameter is deprecated (support for non-default values will be dropped).
config_param::WORKSPACE
config_param::WORKSPACE_PLACEMENT

Parameter indicating whether the object’s workspace is to be managed by the user or by oneMKL. The two enumerators are equivalent to one another and may be used interchangeably. The interested reader is referred to the page specific to externally-allocated workspaces for more details.

config_param::WORKSPACE_BYTES
config_param::WORKSPACE_EXTERNAL_BYTES

Exact size of the object’s workspace, in bytes. The interested reader is referred to the page specific to externally-allocated workspaces for more details.

config_param::WORKSPACE_ESTIMATE_BYTES

Conservative estimate size of the object’s workspace, in bytes. The interested reader is referred to the page specific to externally-allocated workspaces for more details.

config_param::DESTROY_INPUT

Configuration parameter controlling whether the object is allowed to overwrite input data or not, when configured for out-of-place operations.

config_param::THREAD_LIMIT

Limit on the number of (CPU) threads that may be used by the object when computing a DFT. This configuration parameter is irrelevant for objects committed to GPU devices.

config_param::COMMIT_STATUS

Configuration parameter indicating whether the object is committed to a DFT configuration and to a user-provided sycl::queue instance or not.

config_param::VERSION

Version of oneMKL being used.
This parameter is deprecated.

Note

The configuration parameters represented by config_param::DIMENSION, config_param::FORWARD_DOMAIN, config_param::LENGTHS, config_param::PRECISION, config_param::COMMIT_STATUS, config_param::VERSION, config_param::WORKSPACE_ESTIMATE_BYTES, config_param::WORKSPACE_BYTES, config_param::WORKSPACE_EXTERNAL_BYTES are all read-only: they are not writable.

precision#

This scoped enumeration type is used to represent the configuration value associated with the configuration parameter config_param::PRECISION of oneMKL DFT descriptor objects. Its enumerators identify the various floating-point formats that may be considered. For any oneMKL DFT descriptor object, that configuration value is bound to its type and immutable given its usage as a specialization value for the descriptor class template.

Enumerators of the precision scoped enumeration along with the corresponding floating-point format considered by descriptor objects.#

Enumerator

Corresponding floating-point format

precision::SINGLE

Single-precision floating-point format (FP32).

precision::DOUBLE

Double-precision floating-point format (FP64).

domain#

This scoped enumeration type is used to represent the configuration value associated with the configuration parameter config_param::FORWARD_DOMAIN of oneMKL DFT descriptor objects. Its enumerators identify the types of forward domain that may be considered. For any oneMKL DFT descriptor object, that configuration value is bound to its type and immutable given its usage as a specialization value for the descriptor class template.

Enumerators of the domain scoped enumeration along with the corresponding type of forward domain considered by descriptor objects.#

Enumerator

Corresponding type of forward domain

domain::REAL

Real forward domain.

domain::COMPLEX

Complex forward domain.

config_value#

This scoped enumeration type is used to represent configuration values that cannot be represented with precision, domain, primitive or derived data types for some configuration parameters of oneMKL DFT descriptor objects.

Enumerators of the config_value scoped enumeration along with the matching configuration parameter for descriptor objects.#

Enumerator(s)

Matching configuration parameter(s)

config_value::COMMITTED
config_value::UNCOMMITTED

Possible configuration values associated with the configuration parameter config_param::COMMIT_STATUS indicating whether a descriptor was successfully commited (config_value::COMMITTED) or not (config_value::UNCOMMITTED).

config_value::COMPLEX_COMPLEX

Possible configuration value associated with the configuration parameters config_param::COMPLEX_STORAGE or config_param::CONJUGATE_EVEN_STORAGE. The interested reader is referred to the page specific to configuring data layouts for more details.

config_value::REAL_REAL

Possible configuration value associated with the configuration parameter config_param::COMPLEX_STORAGE. The interested reader is referred to the page specific to configuring data layouts for more details.

config_value::COMPLEX_REAL

Possible configuration value associated with the configuration parameter config_param::CONJUGATE_EVEN_STORAGE. The interested reader is referred to the page specific to configuring data layouts for more details.
This value is deprecated (support for a non-default value associated with config_param::CONJUGATE_EVEN_STORAGE will be dropped)
config_value::INPLACE
config_value::NOT_INPLACE

Possible configuration values associated with the configuration parameter config_param::PLACEMENT indicating whether the DFT computation must be performed in-place (config_value::INPLACE) or not (config_value::NOT_INPLACE).

config_value::WORKSPACE_AUTOMATIC
config_value::WORKSPACE_INTERNAL
config_value::WORKSPACE_EXTERNAL

Possible configuration values associated with the configuration parameter config_param::WORKSPACE (or its alias config_param::WORKSPACE_PLACEMENT). The two enumerators config_value::WORKSPACE_AUTOMATIC and config_value::WORKSPACE_INTERNAL are equivalent to one another and may be used interchangeably. The interested reader is referred to the page specific to externally-allocated workspaces for more details.

config_value::ALLOW
config_value::AVOID

Possible self-explanatory configuration values associated with the configuration parameter config_param::DESTROY_INPUT.

config_value::CCE_FORMAT
config_value::PERM_FORMAT
config_value::PACK_FORMAT
config_value::CCS_FORMAT
Possible configuration values associated with the configuration parameter config_param::PACKED_FORMAT. The interested reader is referred to the page specific to configuring data layouts for more details.
These values are deprecated (support for non-default values associated with config_param::PACKED_FORMAT will be dropped)

Deprecations#

Several enumerators in the scoped enumerations documented above are explicitly assigned values from the oneMKL C interface’s (unscoped) enumerations DFTI_CONFIG_PARAM or DFTI_CONFIG_VALUE. The support for these values via the oneMKL DPC++ interface is now deprecated. Wherever such an unscoped enumerator, say DFTI_X, has been used (or usable) in the oneMKL DPC++ interface, a corresponding scoped enumerator domain::X, precision::X, config_param::X or config_value::X does replace it now as a better-suited subsitute. The explicit assignments of the former to the latter will be removed upon completion of the deprecation period for supporting DFTI_CONFIG_PARAM and DFTI_CONFIG_VALUE enumerators via the DPC++ interface of oneMKL.

Explicitly, users are advised to use

  • precision::SINGLE and precision::DOUBLE instead of DFTI_SINGLE and DFTI_DOUBLE, respectively;

  • domain::REAL and domain::COMPLEX instead of DFTI_REAL and DFTI_COMPLEX, respectively;

  • config_param::FORWARD_DOMAIN, config_param::DIMENSION, config_param::LENGTHS, config_param::PRECISION, config_param::FORWARD_SCALE, config_param::BACKWARD_SCALE, config_param::NUMBER_OF_TRANSFORMS, config_param::COMPLEX_STORAGE, config_param::CONJUGATE_EVEN_STORAGE, config_param::PLACEMENT, config_param::INPUT_STRIDES, config_param::OUTPUT_STRIDES, config_param::FWD_DISTANCE, config_param::BWD_DISTANCE, config_param::WORKSPACE, config_param::PACKED_FORMAT, config_param::COMMIT_STATUS, config_param::VERSION, config_param::THREAD_LIMIT and config_param::DESTROY_INPUT instead of DFTI_FORWARD_DOMAIN, DFTI_DIMENSION, DFTI_LENGTHS, DFTI_PRECISION, DFTI_FORWARD_SCALE, DFTI_BACKWARD_SCALE, DFTI_NUMBER_OF_TRANSFORMS, DFTI_COMPLEX_STORAGE, DFTI_CONJUGATE_EVEN_STORAGE, DFTI_PLACEMENT, DFTI_INPUT_STRIDES, DFTI_OUTPUT_STRIDES, DFTI_FWD_DISTANCE, DFTI_BWD_DISTANCE, DFTI_WORKSPACE, DFTI_PACKED_FORMAT, DFTI_COMMIT_STATUS, DFTI_VERSION, DFTI_THREAD_LIMIT and DFTI_DESTROY_INPUT, respectively;

  • config_value::COMMITTED, config_value::UNCOMMITTED, config_value::COMPLEX_COMPLEX, config_value::REAL_REAL, config_value::INPLACE, config_value::NOT_INPLACE, config_value::COMPLEX_REAL, config_value::ALLOW, config_value::AVOID, config_value::CCE_FORMAT, config_value::PERM_FORMAT, config_value::PACK_FORMAT and config_value::CCS_FORMAT instead of DFTI_COMMITTED, DFTI_UNCOMMITTED, DFTI_COMPLEX_COMPLEX, DFTI_REAL_REAL, DFTI_INPLACE, DFTI_NOT_INPLACE, DFTI_COMPLEX_REAL, DFTI_ALLOW, DFTI_AVOID, DFTI_CCE_FORMAT, DFTI_PERM_FORMAT, DFTI_PACK_FORMAT and DFTI_CCS_FORMAT, respectively.