Configuration Parameters and Enums

Configuration Parameters and Enums

The following enum classes are defined in the oneapi::mkl::dft namespace which are used for configuring the discrete Fourier transform problem in the descriptor class prior to a call to commit.

enum class

Description

precision

The floating-point precision in which the transform is carried out. Used as a template argument for descriptor class.

domain

The forward domain data type for dft transformation. Used as a template argument for descriptor class.

config_param

The configuration parameters to specify the DFT transformation desired. These can be set and retrieved via the set_value and get_value functions.

config_value

Some possible enum values that the config_param configuration parameters can take on.

precision

The floating-point precision in which the transform is to be carried out. The data must be presented in this precision, the computation is carried out in this precision, and the result is delivered in this precision.

Syntax

enum class precision {
   SINGLE,
   DOUBLE
};

Value

Description

SINGLE

data and transforms are executed using single(fp32) precision

DOUBLE

data and transforms are executed using double(fp64) precision

domain

The discrete Fourier transform supports forward transformations on input sequences of two domains, from the forward domain to the backward domain. The backward transformation operates on input sequences from the backward domain to the forward domain. This domain value defines the forward domain and the backward domain is always implied to be complex-valued.

Syntax

enum class domain {
   REAL,
   COMPLEX
};

Value

Forward domain

Backward domain

Description

REAL

real-valued

complex-valued

Forward transformation is real-to-complex, backward transform is complex-to-real.

COMPLEX

complex-valued

complex-valued

Forward and backward transformations are complex-to-complex.

config_param

enum class config_param {

   FORWARD_DOMAIN,
   DIMENSION,
   LENGTHS,
   PRECISION,

   FORWARD_SCALE,
   BACKWARD_SCALE,

   NUMBER_OF_TRANSFORMS,

   COMPLEX_STORAGE,
   REAL_STORAGE,
   CONJUGATE_EVEN_STORAGE,

   PLACEMENT,

   INPUT_STRIDES,
   OUTPUT_STRIDES,

   FWD_DISTANCE,
   BWD_DISTANCE,

   WORKSPACE,
   ORDERING,
   TRANSPOSE,
   PACKED_FORMAT,
   COMMIT_STATUS
};

Many of the config_param enum’s will take values in config_value or other std::int64_t, std::vector<std::int64_t>, or floating-point precision values as specified in the following table.

Value

Description

FORWARD_DOMAIN

Read-only value of forward domain set at descriptor construction time.

DIMENSION

Read-only value of the dimension of the transformation. Value is a positive integer of type std::int64_t set at descriptor construction.

LENGTHS

For a one-dimensional transform, the transform length is specified by a positive integer value represented in an integer scalar (std::int64_t). For multi-dimensional (\(\geq 2\)) transform, the lengths of each of the dimensions are supplied in an integer vector (std::vector<std::int64_t>) at descriptor construction time.

PRECISION

Read-only value of precision set at descriptor construction time.

FORWARD_SCALE

The forward transform is associated with a scale factor, \(\sigma\), of real floating-point type precision, the default value is 1.0.

BACKWARD_SCALE

The backward transform is associated with a scale factor, \(\sigma\), of real floating-point type precision, the default value is 1.0.

NUMBER_OF_TRANSFORMS

If you need to perform a large number of identical DFTs, you can do this in a single call to a compute_forward function with the value of this equal to the actual number of the transforms. Takes a value of std::int64_t with default value of 1.

COMPLEX_STORAGE

Specifies the data storage format for domain with value of COMPLEX.

REAL_STORAGE

Specifies the data storage format for domain with value of REAL.

CONJUGATE_EVEN_STORAGE

Specifies the data storage format using conjugate-even symmetry of the data which allows to store only half of the mathematical results.

PLACEMENT

Choose between in-place(value is config_value::INPLACE) and out-of-place (value is config_value::NOT_INPLACE) transformations. For in-place transformation, the computational functions overwrite the input data with the output results. The default is config_value::INPLACE. When the configuration parameter is set to config_value::NOT_INPLACE, the input and output data sets must have no common elements.

INPUT_STRIDES

Defines the layout of multi-dimensional input data in computer memory. The value for a d-dimensional dataset is a d-dimensional vector of type std::vector<std::int64_t> representing offsets of elements of the appropriate data type as specified in INPUT_STRIDES and OUTPUT_STRIDES.

OUTPUT_STRIDES

Defines the layout of multi-dimensional output data in computer memory. The value for a d-dimensional dataset is a d-dimensional vector of type std::vector<std::int64_t> representing offsets of elements of the appropriate data type as specified in INPUT_STRIDES and OUTPUT_STRIDES.

FWD_DISTANCE

If computing multiple(batched) transforms, this parameter specifies the distance (in elements) between the first data elements of consecutive data sets in the forward domain. Provided in type std::int64_t, the default value is 1.

BWD_DISTANCE

If computing multiple(batched) transforms, this parameter specifies the distance (in elements) between the first data elements of consecutive data sets in the backward domain. Provided in type std::int64_t, the default value is 1.

WORKSPACE

Some FFT algorithm computation steps require a scratch space for permutations or other purposes. To manage the use of auxiliary storage, set to config_value::ALLOW to permit the use of auxiliary storage and config_value::AVOID to avoid using auxiliary storage if possible.

ORDERING

Some FFT algorithms apply an explicit permutation stage that can be time consuming. The value of config_value::ORDERED (default) applies the data ordering for all transformations. The value of config_value::BACKWARD_SCRAMBLED applies ordering for forward transform, but allows backward transform to have scrambled data if it gives a performance advantage.

TRANSPOSE

A boolean value to indicate providing the transposition of output results (for multi-dimensional transforms). Default value is false.

PACKED_FORMAT

Packing format for complex domain data storage of finite conjugate-even sequences from real-to-complex or complex-to-real transformations.

COMMIT_STATUS

Read-only value indicates whether the descriptor is ready for computation after a successful commit. Value of config_value::COMMITTED indicates a successful call to commit. A value of config_value::UNCOMMITTED (default) is set after descriptor constructor call and before successful call to commit.

config_value

These are some of the non-integer/floating-point values that the config_param configuration parameters can take on.

enum class config_value {

   // for config_param::COMMIT_STATUS
   COMMITTED,
   UNCOMMITTED,

   // for config_param::COMPLEX_STORAGE,
   //     config_param::REAL_STORAGE and
   //     config_param::CONJUGATE_EVEN_STORAGE
   COMPLEX_COMPLEX,
   REAL_COMPLEX,
   REAL_REAL,

   // for config_param::PLACEMENT
   INPLACE,
   NOT_INPLACE,

   // for config_param::ORDERING
   ORDERED,
   BACKWARD_SCRAMBLED,

   // Allow/avoid certain usages
   ALLOW,
   AVOID,
   NONE,

   // for config_param::PACKED_FORMAT for storing conjugate-even finite sequence in real containers
   CCE_FORMAT

};

Parent topic: Discrete Fourier Transform Functions