DFT-related scoped enumeration types

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

Scoped enumeration type	Description
precision	Type for the floating-point format to be used in the desired DFT calculations (for arithmetic operations and data representation). A template parameter prec of this type is used for the descriptor class template.
domain	Type for the kind of forward domain for the desired DFT calculations. A template parameter dom of this type is used for the descriptor class template.
config_param	Type for configuration parameters of descriptor objects.
config_value	Type for non-numeric configuration values corresponding to some of the configuration parameters.

precision

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

Syntax

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

precision enumerator	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

Values in this scoped enumeration type represent the kind of forward domain for the desired DFT(s). As explained in the introduction, the backward domain type is always complex.

Syntax

namespace oneapi::mkl::dft {
  enum class domain {
      REAL,
      COMPLEX
  };
}

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

config_param

Values in this scoped enumeration type represent configuration parameters for descriptor objects.

namespace oneapi::mkl::dft {
  enum class config_param {
      // read-only parameters:
      FORWARD_DOMAIN,
      DIMENSION,
      LENGTHS,
      PRECISION,
      COMMIT_STATUS,
      WORKSPACE_EXTERNAL_BYTES,
      // 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
  };
}

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.

config_param enumerator	Represented configuration parameter	Type of associated configuration value [default value]
FORWARD_DOMAIN	Kind of forward domain for the DFT. This parameter is read-only.	domain [specialization value used for template parameter dom of the descriptor class template]
DIMENSION	Dimension \(d\) of the DFT. This parameter is read-only.	std::int64_t [\(d\)]
LENGTHS	Lengths \(\lbrace n_1, \ldots, n_d\rbrace\) of the DFT. This parameter is read-only and can only be set via the parameterized constructors.	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 format to use for the DFT data and computation. This parameter is read-only.	precision [specialization value used for template parameter prec of the descriptor class template]
COMMIT_STATUS	Status flag indicating whether the object is ready for computations after a successful call to its commit member function. This parameter is read-only.	config_value (possible values are config_value::COMMITTED or config_value::UNCOMMITTED). [config_value::UNCOMMITTED]
FORWARD_SCALE	\(\sigma_{\delta}\) for the forward DFT (\(\delta = -1\)).	float (resp. double) for single-precision (resp. double-precision) descriptors [\(1.0\)]
BACKWARD_SCALE	\(\sigma_{\delta}\) for the backward DFT (\(\delta = +1\)).	float (resp. double) for single-precision (resp. double-precision) descriptors [\(1.0\)]
NUMBER_OF_TRANSFORMS	Batch size \(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 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)\) [see the dedicated section]
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)\) [see the dedicated section]
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 the set_workspace member function. This parameter is read-only and can be queried only if the descriptor object is committed.	std::int64_t [N/A]

config_value

Values in this scoped enumeration type represent possible non-numeric configuration values associated with some configuration parameters.

namespace oneapi::mkl::dft {
  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,
  };
}

config_value enumerators	Description
COMMITTED UNCOMMITTED	Possible configuration values associated with the configuration parameter config_param::COMMIT_STATUS indicating whether a descriptor object was successfully commited (config_value::COMMITTED) or not (config_value::UNCOMMITTED).
COMPLEX_COMPLEX REAL_REAL	Possible configuration values associated with the configuration parameter config_param::COMPLEX_STORAGE indicating whether real and imaginary parts of complex entries are stored separately (config_value::REAL_REAL) or not (config_value::COMPLEX_COMPLEX). More details are available in the page dedicated to data storage.
INPLACE 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).
WORKSPACE_AUTOMATIC WORKSPACE_EXTERNAL	Possible configuration values associated with the configuration parameter config_param::WORKSPACE_PLACEMENT. More details are available in the page dedicated to workspace placement.

Parent topic: Discrete Fourier Transform Functions