descriptor#

The descriptor class defines a discrete Fourier transform problem to be computed.

Description

The discrete Fourier transform problem is defined through the use of the oneapi::mkl::dft::descriptor class which lives in the oneapi::mkl::dft:: namespace. The enum and config_param values associated with the descriptor class can be found in Configuration Parameters and Enums including precision, domain and config_param. The descriptor class allows to set several configuration parameters using set_value (and query using get_value) and then upon call to commit with a sycl::queue, is ready to be used in computations on the specified device.

This class is then passed to a compute_forward or compute_backward function along with the data for the actual transformation to be applied.

Note

The compute_forward and compute_backward functions may need to be able to access the internals of the descriptor to apply the transform, this could be done for instance, by labeling them as friend functions of the descriptor class.

descriptor class#

Syntax

The descriptor class lives in the oneapi::mkl::dft namespace.

namespace oneapi::mkl::dft {

   template <oneapi::mkl::dft::precision prec, oneapi::mkl::dft::domain dom>
   class descriptor {
    public:

       // Syntax for 1-dimensional DFT
       descriptor(std::int64_t length);

       // Syntax for d-dimensional DFT
       descriptor(std::vector<std::int64_t> dimensions);

       descriptor(const descriptor&);

       descriptor(descriptor&&);

       descriptor& operator=(const descriptor&);

       descriptor& operator=(descriptor&&);

       ~descriptor();

       void set_value(config_param param, ...);

       void get_value(config_param param, ...);

       void commit(sycl::queue &queue);

    };

}

Descriptor class template parameters

precision prec: Specifies the floating-point precision in which the transform is to be carried out.
domain dom: Specifies the forward domain for the transformations.

Descriptor class member functions

Routines	Description
constructors	Initialize descriptor for 1-dimensional or N-dimensional transformations
assignment operators	Assignment operator.
set_value	Sets one particular configuration parameter with the specified configuration value.
get_value	Gets the configuration value of one particular configuration parameter.
commit	Performs all initialization for the actual FFT computation.

Descriptor class constructors#

The constructors for the discrete Fourier transform descriptor class with default configuration settings for a given precision, forward domain type and dimension of the transform.

The constructors allocate memory for the descriptor data structure and instantiate it with all the default configuration settings for the precision, (forward) domain, and dimensions of the transform. The constructors do not perform any significant computational work, such as computation of twiddle factors. The function commit does this work after use of the function set_value to set values of all necessary parameters.

The copy constructor performs a deep copy of the descriptor.

Syntax (one-dimensional transform)

namespace oneapi::mkl::dft {

   template <oneapi::mkl::dft::precision prec, oneapi::mkl::dft::domain dom>
   descriptor<prec,dom>(std::int64_t length);

}

Syntax (multi-dimensional transform)

namespace oneapi::mkl::dft {

   template <oneapi::mkl::dft::precision prec, oneapi::mkl::dft::domain dom>
   descriptor<prec,dom>(std::vector<std::int64_t> dimensions);

}

Copy constructor

namespace oneapi::mkl::dft {

   template <oneapi::mkl::dft::precision prec, oneapi::mkl::dft::domain dom>
   descriptor<prec,dom>(const descriptor<prec,dom>& other);

}

Move constructor

namespace oneapi::mkl::dft {

   template <oneapi::mkl::dft::precision prec, oneapi::mkl::dft::domain dom>
   descriptor<prec,dom>(descriptor<prec,dom>&& other);

}

Input Parameters

length: dimension(length) of data for a 1-dimensional transform.
dimensions: vector of \(d\geq 0\) dimensions(lengths) of data for a d-dimensional transform.
other: another descriptor of the same type to copy or move

Throws

The descriptor() constructor shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here:

oneapi::mkl::host_bad_alloc(): If any memory allocations on host have failed, for instance due to insufficient memory.
oneapi::mkl::unimplemented(): If length of dimensions vector is larger than is supported by the library implementation.

Descriptor class member table: Descriptor class member functions

Descriptor class assignment operators#

The copy assignment operator results in a deep copy.

Copy assignment

namespace oneapi::mkl::dft {

   template <oneapi::mkl::dft::precision prec, oneapi::mkl::dft::domain dom>
   descriptor<prec,dom>& descriptor<prec,dom>::operator=(const descriptor<prec,dom>& other);

}

Move assignment

namespace oneapi::mkl::dft {

   template <oneapi::mkl::dft::precision prec, oneapi::mkl::dft::domain dom>
   descriptor<prec,dom>& descriptor<prec,dom>::operator=(descriptor<prec,dom>&& other);

}

Input Parameters

other: The descriptor to copy or move from.

Throws

The assignment opererator shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here:

oneapi::mkl::host_bad_alloc(): If any memory allocations on host have failed, for instance due to insufficient memory.

Descriptor class member table: Descriptor class member functions

set_value#

Sets DFT configuration values before commit.

Description

This function sets one particular configuration parameter with the specified configuration value. Each configuration parameter is a named constant, and the configuration value must have the corresponding type, which can be a named constant or a native type. For available configuration parameters and the corresponding configuration values, see config_param. All calls to set_param must be done before commit.

Syntax

namespace oneapi::mkl::dft {

   template <oneapi::mkl::dft::precision prec, oneapi::mkl::dft::domain dom>
   void descriptor<prec,dom>::set_value(config_param param, ...);

}

Input Parameters

param: The enum value of config_param to be set.

…: The corresponding value or container corresponding to the specific parameter. Defined in config_param.

Throws

The descriptor::set_value() routine shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here:

oneapi::mkl::invalid_argument(): If the provided config_param or config_value is not valid.
oneapi::mkl::unimplemented(): If the provided config_param or config_value is valid, but not supported by the library implementation.

Descriptor class member table: Descriptor class member functions

get_value#

Retrieves current DFT configuration values.

Description

This function gets one particular configuration parameter with the specified configuration value. Each configuration parameter is a named constant, and the configuration value must have the corresponding type, which can be a named constant or a native type. For available configuration parameters and the corresponding configuration values, see config_param.

Syntax

namespace oneapi::mkl::dft {

   template <oneapi::mkl::dft::precision prec, oneapi::mkl::dft::domain dom>
   void descriptor<prec,dom>::get_value(config_param param, ...);

}

Input Parameters

param: The enum value of config_param to be retrieved.

…: The corresponding value or container corresponding to the specific parameter. Defined in config_param.

Throws

The descriptor::get_value() routine shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here:

oneapi::mkl::invalid_argument(): If the requested config_param is not correct.

Descriptor class member table: Descriptor class member functions

commit#

Finalizes DFT descriptor after all configuration parameters have been set.

Description

This function completes initialization of a previously created descriptor, which is required before the descriptor can be used for FFT computations. Typically, committing the descriptor performs all initialization that is required for the actual FFT computation on the device specified through input queue. The initialization performed by the function may involve exploring different factorizations of the input length to find the optimal computation method.

All calls to the set_value function to change configuration parameters of a descriptor need to happen after the constructor call for the descriptor class and before a call to commit. Typically, a commit function call is immediately followed by a computation function call (see compute_forward or compute_backward)

Syntax

namespace oneapi::mkl::dft {

   template <oneapi::mkl::dft::precision prec, oneapi::mkl::dft::domain dom>
   void descriptor<prec,dom>::commit(sycl::queue& queue);

}

Input Parameters

queue: Valid DPC++ queue specifying the device and context on which the transformation will be executed.

Throws

The following oneMKL exceptions may be thrown in this function:

The descriptor::commit() routine shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here:

oneapi::mkl::invalid_argument(): If the queue is found to be invalid in any way.
oneapi::mkl::host_bad_alloc(): If any host side only memory allocations fail, for instance due to lack of memory.
oneapi::mkl::device_bad_alloc(): If any device or shared memory allocation fail.

Descriptor class member table: Descriptor class member functions

Parent topic: Discrete Fourier Transform Functions

descriptor

Contents

descriptor#

descriptor class#

Descriptor class constructors#

Descriptor class assignment operators#

set_value#

get_value#

commit#