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();
void set_value(config_param param, ...);
void get_value(config_param param, ...);
void commit(sycl::queue &queue);
};
}
Descriptor class template parameters
Descriptor class member functions
Routines |
Description |
|---|---|
Initialize descriptor for 1-dimensional or N-dimensional transformations |
|
Sets one particular configuration parameter with the specified configuration value. |
|
Gets the configuration value of one particular configuration parameter. |
|
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.
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);
}
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.
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
dimensionsvector is larger than is supported by the library implementation.
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