compute_forward

This function computes the forward 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 forward DFT calculations, this function computes the forward transform defined by that object.

The compute_forward 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_forward 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_forward (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_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::mkl::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::mkl::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::mkl::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 object of the descriptor class, 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 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 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 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 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 oneapi::mkl::dft::compute_forward 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_forward (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_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::mkl::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::mkl::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::mkl::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 object of the descriptor class, 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 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 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 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 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 oneapi::mkl::dft::compute_forward() 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 forward DFT, and can be passed as a dependency to other routines that may depend on the result of the forward transform(s) before proceeding with other operations.

Parent topic: Discrete Fourier Transform Functions