The `descriptor` class#

Objects of the descriptor class define DFT(s) to be computed.

Description

Any desired (batched) DFT is to be fully determined by an object of the oneapi::mkl::dft::descriptor class, defined in the oneapi::mkl::dft namespace. The scoped enumeration types precision, domain, config_param and config_value defined in the same namespace (and the corresponding ranges of values) are relevant to the definition and configurations of objects of the descriptor class. The descriptor class allows the user to set several (resp. query all) configuration parameters for (resp. from) any of its instances by using their set_value (resp. get_value) member function.

Invoking the member function commit of an object of the descriptor class effectively commits that object to the desired DFT calculations, as configured and determined by that very object, on the specified device encapsulated by the sycl::queue object required by that function.

The desired forward (resp. backward) DFT calculations may then be computed by passing such a committed descriptor object to the compute_forward (resp. compute_backward) function (defined in the oneapi::mkl::dft namespace as well), along with the relevant data containers (sycl::buffer object(s) or pointer(s) to a device-accessible USM allocations) for the desired DFT(s). This function makes the descriptor object enqueue the operations relevant for the desired calculations to the sycl::queue object it was given when committing it.

Note

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

Syntax

The descriptor class is defined in the oneapi::mkl::dft namespace.

namespace oneapi::mkl::dft {

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

       // Constructor for 1-dimensional DFT
       descriptor(std::int64_t length); // d = 1;

       // Constructor for d-dimensional DFT
       descriptor(std::vector<std::int64_t> lengths); // d = lengths.size();

       descriptor(const descriptor&);

       descriptor(descriptor&&);

       descriptor& operator=(const descriptor&);

       descriptor& operator=(descriptor&&);

       ~descriptor();

       void set_value(oneapi::mkl::dft::config_param param, ...);

       void get_value(oneapi::mkl::dft::config_param param, ...);

       void set_workspace(sycl::buffer<scalar_type, 1> &workspaceBuf);
       void set_workspace(scalar_type* workspaceUSM);

       void commit(sycl::queue &queue);

    };

}

Descriptor class template parameters

precision prec: Specifies the floating-point precision in which the user-provided data is to be provided, the transform is to be carried out and the results are to be returned. The possible specialization values are oneapi::mkl::dft::precision::SINGLE and oneapi::mkl::dft::precision::DOUBLE. Objects of the descriptor class specialized with precision template parameter prec as value oneapi::mkl::dft::precision::SINGLE (resp. oneapi::mkl::dft::precision::DOUBLE) are referred to as “single-precision descriptors” (resp. “double-precision descriptors”).
domain dom: Specifies the forward domain of the transform. The possible specialization values are oneapi::mkl::dft::domain::COMPLEX and oneapi::mkl::dft::domain::REAL. Objects of the descriptor class specialized with domain template parameter dom as value oneapi::mkl::dft::precision::COMPLEX (resp. oneapi::mkl::dft::precision::REAL) are referred to as “complex descriptors” (resp. “real descriptors”).

Descriptor class member functions

Routines	Description
constructors	Creates and default-initializes a `descriptor` object for a \(d\)-dimensional DFT of user-defined length(s) \(\lbrace n_1, \ldots, n_d\rbrace\).
assignment operators	Performs a deep copy of or moves the argument.
set_value	Sets a configuration value for a specific configuration parameter.
get_value	Queries the configuration value associated with a particular configuration parameter.
set_workspace	Sets the external workspace to use when `config_param::WORKSPACE_PLACEMENT` is set to `config_value::WORKSPACE_EXTERNAL`.
commit	Commits the `descriptor` object to enqueue the operations relevant to the (batched) DFT(s) it determines to a given, user-provided `sycl::queue` object; completes all initialization work relevant to and required by the chosen, device-compliant implementation for the particular DFT, as defined by the `descriptor` object.

Descriptor class constructors#

The constructors for the descriptor object instantiate it with all the relevant default configuration settings (which may depend on the specialization values used for the precision template parameter prec and for the domain template parameter dom). The constructors do not perform any significant initialization work as changes in the object’s configuration(s) may be operated thereafter (via its set_value member function) and modify significantly the nature of that work.

The copy constructor performs a deep copy of descriptor objects.

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 (\(d\)-dimensional transform with \(d > 0\))

namespace oneapi::mkl::dft {

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

}

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: Length \(n_1 > 0\) of the data sequence(s) for one-dimensional transform(s).
lengths: Vector of \(d > 0\) lengths \(\lbrace n_1, \ldots, n_d\rbrace\) of the data sequence(s) for \(d\)-dimensional transform(s). The values are to be provided in that order and such that \(n_j > 0,\ \forall j \in \lbrace 1, \ldots, d \rbrace\).
other: Another descriptor object of the same type to copy or move.

Throws

The descriptor::descriptor() constructors shall throw the following exception 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 the dimension \(d\), i.e., the size of vector lengths, is larger than what 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 object to copy or move from.

Throws

The assignment operators 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#

The set_value member function of the descriptor class sets a configuration value corresponding to a (read-write) configuration parameter for the DFT(s) that a descriptor object defines. This function is to be used as many times as required for all the necessary configuration parameters to be set prior to committing the descriptor object (by calling its member function commit).

This function requires and expects exactly two arguments: it sets the configuration value (second argument) corresponding to the configuration parameter (first argument) param of type oneapi::mkl::dft::config_param. The type of the configuration value (second argument) to be set depends on the value of param: it can be oneapi::mkl::dft::config_value or a native type like std::int64_t or float (more details available here).

Syntax

namespace oneapi::mkl::dft {

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

}

Input Parameters

param: One of the possible values of type config_param representing the (writable) configuration parameter to be set.

…: An element of the appropriate type for the configuration value corresponding to the targeted configuration parameter param (appropriate type defined here).

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 and/or configuration value is not valid.
oneapi::mkl::unimplemented(): If the provided config_param and configuration value are valid, but not supported by the library implementation.

Descriptor class member table: Descriptor class member functions

get_value#

The get_value member function of the descriptor class queries the configuration value corresponding to any configuration parameter for the DFT that a descriptor object defines.

This function requires and expects exactly two arguments: it returns the configuration value (into the element pointed by the second argument) corresponding to the queried configuration parameter (first argument) param of type oneapi::mkl::dft::config_param. The type of the second argument depends on the value of param: it is a pointer to a writable element of type oneapi::mkl::dft::domain, oneapi::mkl::dft::precision, oneapi::mkl::dft::config_value or a native type like std::int64_t or float (more details available here).

Note

The value returned by get_value corresponds to the latest value set for the corresponding configuration parameter being queried or the corresponding default value if that parameter was not set or if it is not writable, even if that value was set after the descriptor was committed.

Syntax

namespace oneapi::mkl::dft {

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

}

Input Parameters

param: One of the possible values of type config_param representing the configuration parameter being queried.

…: A pointer to a writable element of the appropriate type for the configuration value corresponding to the queried configuration parameter param (appropriate type of pointed element defined here).

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 valid.

Descriptor class member table: Descriptor class member functions

set_workspace#

Sets the workspace for when config_param::WORKSPACE_PLACEMENT is set to config_value::WORKSPACE_EXTERNAL.

Description

This function sets the workspace to use when computing DFTs for when an external workspace is set. This function may only be called after the descriptor has been committed. The size of the provided workspace must be equal to or larger than the required workspace size obtained by calling descriptor<prec, dom>::get_value(config_param::WORKSPACE_EXTERNAL_BYTES, &workspaceBytes).

A descriptor where config_value::WORKSPACE_EXTERNAL is specified for config_param::WORKSPACE_PLACEMENT is not a valid descriptor for compute calls until this function has been successfully called.

The type of workspace must match the compute calls for which it is used. That is, if the workspace is provided as a sycl::buffer, the compute calls must also use sycl::buffer for their arguments. Likewise, a USM allocated workspace must only be used with USM compute calls. Failing to do this will result in an invalid descriptor for compute calls.

If the workspace is a USM allocation, the user must not use it for other purposes in parallel whilst the DFT compute_forward or compute_backward are in progress.

This function can be called on committed descriptors where the workspace placement is not config_value::WORKSPACE_EXTERNAL. The provided workspace may or may not be used in compute calls. However, the aforementioned restrictions will still apply.

Syntax (buffer workspace)

namespace oneapi::mkl::dft {

   template <oneapi::mkl::dft::precision prec, oneapi::mkl::dft::domain dom>
   void descriptor<prec,dom>::set_workspace(sycl::buffer<scalar_type, 1> &workspaceBuf);
}

Syntax (USM workspace)

namespace oneapi::mkl::dft {

   template <oneapi::mkl::dft::precision prec, oneapi::mkl::dft::domain dom>
   void descriptor<prec,dom>::set_workspace(scalar_type* workspaceUSM);

}

Input Parameters

workspaceBuf: A workspace buffer where scalar_type is the floating-point type according to prec. This buffer must be sufficiently large or an exception will be thrown. A sub-buffer cannot be used.
workspaceUSM: A workspace USM allocation where scalar_type is the floating-point type according to prec. This allocation must be accessible on the device on which the descriptor is committed. It is assumed that this USM allocation is sufficiently large. The pointer is expected to be aligned to scalar_type.

Throws

The descriptor::set_workspace() 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 buffer workspaceBuf is not sufficiently large or is a sub-buffer, or if the provided USM allocation workspaceUSM is nullptr when an external workspace of size greater than zero is required.
oneapi::mkl::uninitialized(): If set_workspace is called before the descriptor is committed.

Descriptor class member table: Descriptor class member functions

commit#

The commit member function commits a descriptor object to the DFT calculations it defines consistently with its configuration settings, by completing all the initialization work (e.g., algorithm selection, algorithm tuning, choice of factorization, memory allocations, calculation of twiddle factors, etc.) required by the chosen implementation for the desired DFT(s) on the targeted device. Objects of the descriptor class must be committed prior to using them in any call to compute_forward or compute_backward (which trigger actual DFT calculations).

As specified above, all required configuration parameters must be set before this function is called. Any change in configuration operated on a descriptor object via a call to its set_value member function after it was committed results in an undefined state not suitable for computation until this commit member function is called again.

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 sycl::queue object to which the operations relevant to the desired DFT(s) are to be enqueued.

Throws

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 (if the descriptor object’s configuration was found to be inconsistent, for instance):

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

The descriptor class

Contents

The `descriptor` class#

Descriptor class constructors#

Descriptor class assignment operators#

set_value#

get_value#

set_workspace#

commit#

The descriptor class

Contents

The descriptor class#

Descriptor class constructors#

Descriptor class assignment operators#

set_value#

get_value#

set_workspace#

commit#

The `descriptor` class#