The descriptor class template

The `descriptor` class template#

Instances of any oneapi::mkl::dft::descriptor class define DFT(s) to be computed. The usage of prepended namespace specifiers oneapi::mkl::dft is omitted below for conciseness.

Description#

Any desired DFT is fully defined by an instance of a specialization of the descriptor class template, declared 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 such objects. Users can set several (resp. query all) configuration parameters for (resp. from) any descriptor object by using its set_value (resp. get_value) member functions.

Invoking the commit member function of a descriptor object effectively commits it to the desired DFT calculations (as it defines it) on the specific 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 a 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 template.

Syntax

namespace oneapi::mkl::dft {

   template <precision prec, domain dom>
   class descriptor {
    private:
       using real_scalar_t = std::conditional_t<prec == precision::DOUBLE, double, float>;

    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(config_param param, config_value value);
       void set_value(config_param param, std::int64_t value);
       void set_value(config_param param, real_scalar_t value);
       [[deprecated("Use set_value(config_param, const std::vector<std::int64_t>&) instead.")]]
       void set_value(config_param param, const std::int64_t* value);
       void set_value(config_param param, const std::vector<std::int64_t>& value);
       template <typename T, std::enable_if_t<std::is_integral_v<T>, bool> = true>
       void set_value(config_param param, T value) {
           set_value(param, static_cast<std::int64_t>(value));
       }
       template <typename T, std::enable_if_t<std::is_floating_point_v<T>, bool> = true>
       void set_value(config_param param, T value) {
           set_value(param, static_cast<real_scalar_t>(value));
       }
       [[deprecated("This set_value member function is deprecated.")]]
       void set_value(config_param param, ...);

       void get_value(config_param param, config_value* value_ptr) const;
       void get_value(config_param param, domain* value_ptr) const;
       void get_value(config_param param, precision* value_ptr) const;
       void get_value(config_param param, std::int64_t* value_ptr) const;
       void get_value(config_param param, real_scalar_t* value_ptr) const;
       void get_value(config_param param, std::vector<std::int64_t>* value_ptr) const;
       [[deprecated("This get_value member function is deprecated.")]]
       void get_value(config_param param, ...) const;

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

       void commit(sycl::queue &queue);

    };
}

Template parameters

precision prec: Specifies the floating-point format of the user-provided data, the results, and the precision of the floating-point operations to be enqueued. The possible specialization values are precision::SINGLE and precision::DOUBLE, corresponding to single-precision (FP32) and double-precision (FP64) floating-point formats, respectively . Objects of a descriptor class specialized with precision::SINGLE (resp. precision::DOUBLE) as prec are referred to as “single-precision descriptors” (resp. “double-precision descriptors”).
domain dom: Specifies the type of forward domain for the transform. The possible specialization values are domain::COMPLEX and domain::REAL, corresponding to complex and real forward domains, respectively. Objects of the descriptor class specialized with domain::COMPLEX (resp. domain::REAL) as dom are referred to as “complex descriptors” (resp. “real descriptors”).

Member functions of the descriptor class template

Routines	Description
constructors	Create a `descriptor` object. The parameterized constructors enable the (one-time) definition of the length(s) \(\lbrace n_1, \ldots, n_d\rbrace\) (the dimension \(d\) is deduced accordingly). The parameterized constructors default-initialize the object; copy and move constructors do not.
assignment operators	Perform a deep copy of or moves the argument.
`set_value` member functions	Set a configuration value for a specific configuration parameter.
`get_value` member functions	Query the configuration value associated with a particular configuration parameter.
`set_workspace` member function	Equips the `descriptor` object with an external workspace.
`commit` member function	Commits the `descriptor` object to enqueue the operations relevant to the 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.

Constructors#

The parameterized constructors for a descriptor object instantiate it with all the relevant default configuration settings (which may depend on the specialization values for prec and 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 functions) and modify significantly the nature of that work.

The copy constructor performs a deep copy of descriptor objects.

The move constructor transfers the resources owned by a descriptor object, without copying them.

Parameterized constructor (one-dimensional transform)

namespace oneapi::mkl::dft {

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

}

Parameterized constructor (transform of any dimension)

namespace oneapi::mkl::dft {

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

}

Copy constructor

namespace oneapi::mkl::dft {

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

}

Move constructor

namespace oneapi::mkl::dft {

   template <precision prec, domain dom>
   descriptor<prec,dom>::descriptor(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 constructors 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 the dimension \(d\), i.e., the size of lengths, is larger than what is supported by the library implementation.

Descriptor class member table: Member functions of the descriptor class template

Assignment operators#

The copy assignment operator results in a deep copy.

Copy assignment

namespace oneapi::mkl::dft {

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

}

Move assignment

namespace oneapi::mkl::dft {

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

}

Input Parameters

other: Another descriptor object to copy or move from.

Throws

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

Descriptor class member table: Member functions of the descriptor class template

`set_value` member functions#

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

All these functions require and expect exactly two arguments: they set the given configuration value (second argument) for a desired configuration parameter (first argument), represented by param of type config_param. The expected type of the associated configuration value (second argument) depends on param and is specified in the section dedicated to the config_param type and its enumerators (unless a deprecated version is used). The expected type of configuration value determines which of the set_value overloads is to be used for a specific value of param.

Syntax for integer-valued parameters

namespace oneapi::mkl::dft {

   template <precision prec, domain dom>
   void descriptor<prec,dom>::set_value(config_param param, std::int64_t value);
}