Scoped enumerations

oneMKL - Data Parallel C++ Developer Reference

Download PDF

ID 772045

Date 10/31/2024

Version

Public

Visible to Intel only — GUID: GUID-64F754E3-0824-4345-9E06-5A8C5E698427

View Details

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 of the DFT.
`config_param::LENGTHS`	Length(s) of the DFT.
`config_param::PRECISION`	Floating-point format for the DFT.
`config_param::FORWARD_SCALE`	Scaling factor of the forward DFT, i.e., .
`config_param::BACKWARD_SCALE`	Scaling factor of the backward DFT, i.e., .
`config_param::NUMBER_OF_TRANSFORMS`	Batch size 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.

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

oneMKL - Data Parallel C++ Developer Reference

Scoped enumerations

`config_param`

`precision`

`domain`

`config_value`

Deprecations