DFT-related scoped enumeration types

DFT-related scoped enumeration types#

The following scoped enumeration types, defined in the oneapi::mkl::dft namespace, are used for constructing and configuring objects of the descriptor class consistently with the DFT(s) they are meant to define.

Scoped enumeration type	Description
precision	Represents the precision of the floating-point data format and of the floating-point arithmetic to be used for the desired DFT calculations. A template parameter `prec` of this type is used for the descriptor class.
domain	Represents the type of forward domain for the desired DFT(s). A template parameter `dom` of this type is used for the descriptor class.
config_param	Represents configuration parameters for objects of the descriptor class. The configuration values associated with the configuration parameters can be retrieved (resp. set, for writable parameters) via the object’s get_value (resp. set_value) member function.
config_value	Represents the possible configuration values for some of the configuration parameters that may take only a few determined, non-numeric values.

precision#

This scoped enumeration type represents the precision of the floating-point format to be used for the desired DFT(s). The same precision is to be used for the user-provided data, the computation being carried out by oneMKL and the results delivered by oneMKL.

Syntax

enum class precision {
   SINGLE,
   DOUBLE
};

Value	Description
SINGLE	Single-precision floating-point format (FP32) is used for data representation and arithmetic operations.
DOUBLE	Double-precision floating-point format (FP64) is used for data representation and arithmetic operations.

domain#

This scoped enumeration type represents the type of forward domain for the desired DFTs (as explained in the introduction, the backward domain type is always complex).

Syntax

enum class domain {
   REAL,
   COMPLEX
};

Value	Description
REAL	The forward domain is the set of real \(d\)-dimensional periodic sequences.
COMPLEX	The forward domain is the set of complex \(d\)-dimensional periodic sequences.

config_param#

This scoped enumeration type represents configuration parameters for objects of the descriptor class.

enum class config_param {
   // read-only parameters:
   FORWARD_DOMAIN,
   DIMENSION,
   LENGTHS,
   PRECISION,
   COMMIT_STATUS,
   // writable parameters:
   FORWARD_SCALE,
   BACKWARD_SCALE,

   NUMBER_OF_TRANSFORMS,

   COMPLEX_STORAGE,

   PLACEMENT,

   FWD_STRIDES,
   BWD_STRIDES,
   INPUT_STRIDES, // deprecated
   OUTPUT_STRIDES, // deprecated

   FWD_DISTANCE,
   BWD_DISTANCE,

   WORKSPACE_PLACEMENT,
   WORKSPACE_EXTERNAL_BYTES
};

Configuration parameters represented by config_param::FORWARD_DOMAIN and config_param::PRECISION are associated with configuration values of type domain and precision respectively. Other configuration parameters are associated with configuration values of type config_value or of a native type like std::int64_t, std::vector<std::int64_t>, float or double. This is further specified in the following table.

Value of `config_param`	Represented configuration parameter(s)	Type of associated configuration value [default value]
FORWARD_DOMAIN	Type of forward domain, set at construction time as the specialization value of domain template parameter `dom`. This parameter is read-only.	domain [`dom`]
DIMENSION	Value of the dimension \(d\) of the desired DFTs, set at construction time. This parameter is read-only.	`std::int64_t` [\(d\)]
LENGTHS	Values \(\lbrace n_1, \ldots, n_d\rbrace\) of the periods (or “lengths”) of the desired DFT, set at construction time. This parameter is read-only.	`std::vector<std::int64_t>` of size \(d\) or, if \(d = 1\), `std::int64_t` [`std::vector<int64_t>({n_1,...,n_d})`]
PRECISION	Floating-point precision to be considered by and used for the DFT calculation(s), set at construction time as the specialization value of precision template parameter `prec`. This parameter is read-only.	precision [`prec`]
COMMIT_STATUS	Status flag indicating whether the object is ready for computations after a successful call to commit. This parameter is read-only.	config_value (possible values are self-explanatory `config_value::COMMITTED` or `config_value::UNCOMMITTED`). [`config_value::UNCOMMITTED`]
FORWARD_SCALE	Value of \(\sigma\) for the forward DFT.	`float` (resp. `double`) for single-precision (resp. double-precision) descriptors [1.0]
BACKWARD_SCALE	Value of \(\sigma\) for the backward DFT.	`float` (resp. `double`) for single-precision (resp. double-precision) descriptors [1.0]
NUMBER_OF_TRANSFORMS	Value of \(M\). This is relevant (and must be set) for batched DFT(s), i.e., if \(M > 1\).	`std::int64_t` [1]
COMPLEX_STORAGE	Data storage type used (relevant for complex descriptors only).	config_value (possible values are `config_value::COMPLEX_COMPLEX` or `config_value::REAL_REAL`) [`config_value::COMPLEX_COMPLEX`]
PLACEMENT	Parameter specifying whether the DFT calculations should be done in-place (results overwriting the input data) or out-of-place (input and output in separate data containers having no common elements). Note: even for out-of-place configurations, some implementations may not preserve the original input data.	config_value (possible values are self-explanatory `config_value::INPLACE` or `config_value::NOT_INPLACE`) [`config_value::INPLACE`]
FWD_STRIDES	Offset and strides defining the layout within a given data sequence in the forward domain.	`std::vector<std::int64_t>` of size \((d+1)\) [defined here]
BWD_STRIDES	Offset and strides defining the layout within a given data sequence in the backward domain.	`std::vector<std::int64_t>` of size \((d+1)\) [defined here]
INPUT_STRIDES (deprecated)	Offset and strides defining the layout within a given input data sequence.	`std::vector<std::int64_t>` of size \((d+1)\) [`std::vector<std::int64_t>(d+1, 0)`]
OUTPUT_STRIDES (deprecated)	Offset and strides defining the layout within a given output data sequence.	`std::vector<std::int64_t>` of size \((d+1)\) [`std::vector<std::int64_t>(d+1, 0)`]
FWD_DISTANCE	Distance in number of elements of implicitly-assumed data type between forward-domain entries \(\left(\cdot\right)^{m}_{k_1, k_2, \ldots, k_d}\) and \(\left(\cdot\right)^{m + 1}_{k_1, k_2, \ldots, k_d}\) for all \(0\leq m < M - 1\) and \(\left(k_1, k_2, \ldots, k_d\right)\) in valid range. This is relevant (and must be set) for batched DFT(s), i.e., if \(M > 1\).	`std::int64_t` [0]
BWD_DISTANCE	Distance in number of elements of implicitly-assumed data type between backward-domain entries \(\left(\cdot\right)^{m}_{k_1, k_2, \ldots, k_d}\) and \(\left(\cdot\right)^{m + 1}_{k_1, k_2, \ldots, k_d}\) for all \(0\leq m < M - 1\) and \(\left(k_1, k_2, \ldots, k_d\right)\) in valid range. This is relevant (and must be set) for batched DFT(s), i.e., if \(M > 1\).	`std::int64_t` [0]
WORKSPACE_PLACEMENT	Some FFT algorithm computation steps require a scratch space for permutations or other purposes. This parameter controls whether this scratch space is automatically allocated or provided by the user.	config_value (possible values are `config_value::WORKSPACE_AUTOMATIC` or `config_value::WORKSPACE_EXTERNAL`). [`config_value::WORKSPACE_AUTOMATIC`]
WORKSPACE_EXTERNAL_BYTES	The required minimum external workspace size for use by set_workspace. A read-only value, on committed descriptors only.	`std::int64_t`

config_value#

This scoped enumeration type represents possible non-numeric configuration values associated with some configuration parameters.

enum class config_value {
   // for config_param::COMMIT_STATUS
   COMMITTED,
   UNCOMMITTED,

   // for config_param::COMPLEX_STORAGE,
   COMPLEX_COMPLEX,
   REAL_REAL,

   // for config_param::PLACEMENT
   INPLACE,
   NOT_INPLACE

   // For config_param::WORKSPACE_PLACEMENT
   WORKSPACE_AUTOMATIC,
   WORKSPACE_EXTERNAL,
};

Parent topic: Discrete Fourier Transform Functions