compute_backward#

This function computes the backward DFT(s), as defined by an instantiation of the descriptor class, on user-provided data.

Description

Given a successfully committed descriptor object whose configuration is not inconsistent with backward DFT calculations, this function computes the backward transform defined by that object.

The compute_backward function requires a successfully committed object of the descriptor class and one, two or four “data container” arguments (depending on the configuration of the descriptor object). If using (pointers to) USM allocations as data containers, this function 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 tracking the progress of the DFT calculations enqueued by this function.

Note

The compute_backward function may need to access the internals and private/protected members of the descriptor class. This could be done, for instance, by labeling it as a friend function to the descriptor class.

compute_backward (Buffer version)#

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

namespace oneapi::mkl::dft {

   template <typename descriptor_type, typename data_type>
   void compute_backward( 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::mkl::dft {

   template <typename descriptor_type typename data_type>
   void compute_backward( 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::mkl::dft {

   template <typename descriptor_type, typename input_type, typename output_type>
   void compute_backward( 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::mkl::dft {

   template <typename descriptor_type, typename input_type, typename output_type>
   void compute_backward( 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 object of the descriptor class, whose configuration is not inconsistent with backward 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 single or double precision floating-point, as described by the descriptor’s 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 single or double precision floating-point, as described by the descriptor’s 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 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).
in_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.
in_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.

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 single or double precision floating-point, as described by the descriptor’s 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 single or double precision floating-point, as described by the descriptor’s 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 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).
out_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.
out_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.

Throws

The oneapi::mkl::dft::compute_backward 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 descriptor object desc is invalid, for instance, if its configuration value associated with configuration parameter config_param::COMMIT_STATUS is not config_param::COMMITTED.

compute_backward (USM version)#

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

namespace oneapi::mkl::dft {

   template <typename descriptor_type, typename data_type>
   sycl::event compute_backward( 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::mkl::dft {

   template <typename descriptor_type, typename data_type>
   sycl::event compute_backward( 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::mkl::dft {

   template <typename descriptor_type, typename input_type, typename output_type>
   sycl::event compute_backward( 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::mkl::dft {

   template <typename descriptor_type, typename input_type, typename output_type>
   sycl::event compute_backward( 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 object of the descriptor class, whose configuration is not inconsistent with backward 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 single or double precision floating-point, as described by the descriptor’s 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 single or double precision floating-point, as described by the descriptor’s 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 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).
in_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.
in_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.
dependencies: An std::vector<sycl::event> object collecting the events returned by previously enqueued tasks that must be finished before this 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 single or double precision floating-point, as described by the descriptor’s 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 single or double precision floating-point, as described by the descriptor’s 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 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).
out_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.
out_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.

Throws

The oneapi::mkl::dft::compute_backward() 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 descriptor object 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

This function returns a sycl::event object that allows to track progress of the backward DFT, and can be passed as a dependency to other routines that may depend on the result of the backward transform(s) before proceeding with other operations.

Parent topic: Discrete Fourier Transform Functions

compute_backward

Contents

compute_backward#

compute_backward (Buffer version)#

compute_backward (USM version)#