The compute_forward function templates

The `compute_forward` function templates#

The oneapi::math::dft::compute_forward function templates enable the computation of forward DFT(s), as defined by a (committed) oneapi::math::dft::descriptor object, on user-provided data. These function templates are declared in the oneapi::math::dft namespace; the usage of prepended namespace specifiers oneapi::math::dft is omitted below for conciseness.

Description

Given a successfully-committed descriptor object whose configuration is not inconsistent with forward DFT calculations, the forward DFT it defines can be computed using a specialization of (some of) the compute_forward function templates.

The compute_forward functions require a successfully-committed descriptor object and one, two or four “data container” arguments (depending on the configuration of the descriptor object). If using USM allocations as data containers, these functions may also be provided with an std::vector<sycl::event> object collecting dependencies to be observed by the desired DFT calculations and return a sycl::event instance tracking the progress of the enqueued DFT calculations.

Note

The compute_forward functions may need to access the internals and private/protected members of (some) descriptor classes. This could be done, for instance, by labeling them as friend functions to the descriptor class template.

`compute_forward` (Buffer versions)#

Syntax (in-place transform, except for complex descriptors with config_value::REAL_REAL for config_param::COMPLEX_STORAGE)

namespace oneapi::math::dft {

   template <typename descriptor_type, typename data_type>
   void compute_forward(descriptor_type              &desc,
                        sycl::buffer<data_type, 1>   &inout);
}

Syntax (in-place transform, for complex descriptors with config_value::REAL_REAL for config_param::COMPLEX_STORAGE)

namespace oneapi::math::dft {

   template <typename descriptor_type typename data_type>
   void compute_forward(descriptor_type              &desc,
                        sycl::buffer<data_type, 1>   &inout_re,
                        sycl::buffer<data_type, 1>   &inout_im);
}

Syntax (out-of-place transform, except for complex descriptors with config_value::REAL_REAL for config_param::COMPLEX_STORAGE)

namespace oneapi::math::dft {

   template <typename descriptor_type, typename input_type, typename output_type>
   void compute_forward(descriptor_type              &desc,
                        sycl::buffer<input_type, 1>  &in,
                        sycl::buffer<output_type, 1> &out);
}

Syntax (out-of-place transform, for complex descriptors with config_value::REAL_REAL for config_param::COMPLEX_STORAGE)

namespace oneapi::math::dft {

   template <typename descriptor_type, typename input_type, typename output_type>
   void compute_forward(descriptor_type              &desc,
                        sycl::buffer<input_type, 1>  &in_re,
                        sycl::buffer<input_type, 1>  &in_im,
                        sycl::buffer<output_type, 1> &out_re,
                        sycl::buffer<output_type, 1> &out_im);
}

Input Parameters

desc: A fully-configured and committed descriptor object, whose configuration is not inconsistent with forward DFT calculations.
inout: sycl::buffer object of sufficient capacity to store the elements defining all the relevant data sequences, as configured by desc (configured for in-place operations and not with config_value::REAL_REAL for config_param::COMPLEX_STORAGE, if complex).
inout_re: sycl::buffer object of sufficient capacity to store the elements defining the real parts of all the relevant data sequences, as configured by desc. data_type must be float or double, consistently with the desc’s configuration value for config_param::PRECISION. Only with complex descriptors configured for in-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.
inout_im: sycl::buffer object of sufficient capacity to store the elements defining the imaginary parts of all the relevant data sequences, as configured by desc. data_type must be float or double, consistently with the desc’s configuration value for config_param::PRECISION. Only with complex descriptors configured for in-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.
in: sycl::buffer object of sufficient capacity to store the elements defining all the relevant forward-domain data sequences, as configured by desc (configured for out-of-place operations and not with config_value::REAL_REAL for config_param::COMPLEX_STORAGE, if complex).
in_re: sycl::buffer object of sufficient capacity to store the elements defining the real parts of all the relevant forward-domain data sequences, as configured by desc. Only with complex descriptors configured for out-of-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.
in_im: sycl::buffer object of sufficient capacity to store the elements defining the imaginary parts of all the relevant forward-domain data sequences, as configured by desc. Only with complex descriptors configured for out-of-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.

Output Parameters

inout: sycl::buffer object of sufficient capacity to store the elements defining all the relevant data sequences, as configured by desc (configured for in-place operations and not with config_value::REAL_REAL for config_param::COMPLEX_STORAGE, if complex).
inout_re: sycl::buffer object of sufficient capacity to store the elements defining the real parts of all the relevant data sequences, as configured by desc. data_type must be float or double, consistently with the desc’s configuration value for config_param::PRECISION. Only with complex descriptors configured for in-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.
inout_im: sycl::buffer object of sufficient capacity to store the elements defining the imaginary parts of all the relevant data sequences, as configured by desc. data_type must be float or double, consistently with the desc’s configuration value for config_param::PRECISION. Only with complex descriptors configured for in-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.
out: sycl::buffer object of sufficient capacity to store the elements defining all the relevant backward-domain data sequences, as configured by desc (configured for out-of-place operations and not with config_value::REAL_REAL for config_param::COMPLEX_STORAGE, if complex).
out_re: sycl::buffer object of sufficient capacity to store the elements defining the real parts of all the relevant backward-domain data sequences, as configured by desc. Only with complex descriptors configured for out-of-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.
out_im: sycl::buffer object of sufficient capacity to store the elements defining the imaginary parts of all the relevant backward-domain data sequences, as configured by desc. Only with complex descriptors configured for out-of-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.

Throws

The compute_forward functions 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::math::invalid_argument(): If desc is invalid. For instance, if its configuration value associated with configuration parameter config_param::COMMIT_STATUS is not config_param::COMMITTED.

`compute_forward` (USM versions)#

Syntax (in-place transform, except for complex descriptors with config_value::REAL_REAL for config_param::COMPLEX_STORAGE)

namespace oneapi::math::dft {

   template <typename descriptor_type, typename data_type>
   sycl::event compute_forward(descriptor_type                &desc,
                               data_type                      *inout,
                               const std::vector<sycl::event> &dependencies = {});
}

Syntax (in-place transform, for complex descriptors with config_value::REAL_REAL for config_param::COMPLEX_STORAGE)

namespace oneapi::math::dft {

   template <typename descriptor_type, typename data_type>
   sycl::event compute_forward(descriptor_type                &desc,
                               data_type                      *inout_re,
                               data_type                      *inout_im,
                               const std::vector<sycl::event> &dependencies = {});
}

Syntax (out-of-place transform, except for complex descriptors with config_value::REAL_REAL for config_param::COMPLEX_STORAGE)

namespace oneapi::math::dft {

   template <typename descriptor_type, typename input_type, typename output_type>
   sycl::event compute_forward(descriptor_type                &desc,
                               input_type                     *in,
                               output_type                    *out,
                               const std::vector<sycl::event> &dependencies = {});
}

Syntax (out-of-place transform, for complex descriptors with config_value::REAL_REAL for config_param::COMPLEX_STORAGE)

namespace oneapi::math::dft {

   template <typename descriptor_type, typename input_type, typename output_type>
   sycl::event compute_forward(descriptor_type                &desc,
                               input_type                     *in_re,
                               input_type                     *in_im,
                               output_type                    *out_re,
                               output_type                    *out_im,
                               const std::vector<sycl::event> &dependencies = {});
}

Input Parameters

desc: A fully-configured and committed descriptor object, whose configuration is not inconsistent with forward DFT calculations.
inout: Pointer to USM allocation of sufficient capacity to store the elements defining all the relevant data sequences, as configured by desc (configured for in-place operations and not with config_value::REAL_REAL for config_param::COMPLEX_STORAGE, if complex).
inout_re: Pointer to USM allocation of sufficient capacity to store the elements defining the real parts of all the relevant data sequences, as configured by desc. data_type must be float or double, consistently with the desc’s configuration value for config_param::PRECISION. Only with complex descriptors configured for in-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.
inout_im: Pointer to USM allocation of sufficient capacity to store the elements defining the imaginary parts of all the relevant data sequences, as configured by desc. data_type must be float or double, consistently with the desc’s configuration value for config_param::PRECISION. Only with complex descriptors configured for in-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.
in: Pointer to USM allocation of sufficient capacity to store the elements defining all the relevant forward-domain data sequences, as configured by desc (configured for out-of-place operations and not with config_value::REAL_REAL for config_param::COMPLEX_STORAGE, if complex).
in_re: Pointer to USM allocation of sufficient capacity to store the elements defining the real parts of all the relevant forward-domain data sequences, as configured by desc. Only with complex descriptors configured for out-of-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.
in_im: Pointer to USM allocation of sufficient capacity to store the elements defining the imaginary parts of all the relevant forward-domain data sequences, as configured by desc. Only with complex descriptors configured for out-of-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.
dependencies: An std::vector<sycl::event> object collecting the events returned by previously enqueued tasks that must be finished before the desired transform can be calculated.

Output Parameters

inout: Pointer to USM allocation of sufficient capacity to store the elements defining all the relevant data sequences, as configured by desc (configured for in-place operations and not with config_value::REAL_REAL for config_param::COMPLEX_STORAGE, if complex).
inout_re: Pointer to USM allocation of sufficient capacity to store the elements defining the real parts of all the relevant data sequences, as configured by desc. data_type must be float or double, consistently with the desc’s configuration value for config_param::PRECISION. Only with complex descriptors configured for in-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.
inout_im: Pointer to USM allocation of sufficient capacity to store the elements defining the imaginary parts of all the relevant data sequences, as configured by desc. data_type must be float or double, consistently with the desc’s configuration value for config_param::PRECISION. Only with complex descriptors configured for in-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.
out: Pointer to USM allocation of sufficient capacity to store the elements defining all the relevant backward-domain data sequences, as configured by desc (configured for out-of-place operations and not with config_value::REAL_REAL for config_param::COMPLEX_STORAGE, if complex).
out_re: Pointer to USM allocation of sufficient capacity to store the elements defining the real parts of all the relevant backward-domain data sequences, as configured by desc. Only with complex descriptors configured for out-of-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.
out_im: Pointer to USM allocation of sufficient capacity to store the elements defining the imaginary parts of all the relevant backward-domain data sequences, as configured by desc. Only with complex descriptors configured for out-of-place operations with config_value::REAL_REAL for config_param::COMPLEX_STORAGE.

Throws

The compute_forward functions 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::math::invalid_argument(): If desc is invalid. For instance, if its configuration value associated with configuration parameter config_param::COMMIT_STATUS is not config_param::COMMITTED. It will also be thrown if any required input/output pointer is nullptr.

Return Values

These functions return a sycl::event object that enables tracking progress of the forward DFT, and that can be passed as a dependency to other routines, which may depend on the result of the forward transform(s) before proceeding with other operations.

Parent topic: Discrete Fourier Transform Functions

The compute_forward function templates

Contents

The compute_forward function templates#

compute_forward (Buffer versions)#

compute_forward (USM versions)#

The `compute_forward` function templates#

`compute_forward` (Buffer versions)#

`compute_forward` (USM versions)#