Compute Functions

oneMKL - Data Parallel C++ Developer Reference

Download PDF

ID 772045

Date 6/30/2025

Version

Public

Compute Functions

This page describes the function templates oneapi::mkl::experimental::dft::compute_forward and oneapi::mkl::experimental::dft::compute_backward, which both pertain to the calculation of a distributed DFT defined by a committedoneapi::mkl::experimental::dft::distributed_descriptor object desc. These function templates belong to the oneapi::mkl::experimental::dft namespace and are declared in oneapi/mkl/experimental/distributed_dft.hpp (file to be included). The usage of prepended namespace specifier oneapi::mkl::experimental::dft is omitted below for conciseness while the namespace specifier oneapi::mkl::dft is kept for clarity.

namespace oneapi::mkl::experimental::dft {
  /*----------------------- for in-place transforms -----------------------*/
  template <typename descriptor_type, typename data_type>
  sycl::event compute_forward(descriptor_type &desc,
                              data_type *inout,
                              const std::vector<sycl::event> &dependencies = {});
  template <typename descriptor_type, typename data_type>
  sycl::event compute_backward(descriptor_type &desc,
                               data_type *inout,
                               const std::vector<sycl::event> &dependencies = {});
  /*--------------------- for out-of-place transforms ---------------------*/
  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 = {});
  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 = {});
}

Description

The compute_forward (resp. compute_backward) function templates accept a committeddistributed_descriptor object desc followed by one or more data-containing arguments, and enqueue the computation of the forward (resp. backward) DFT that desc defines, i.e., the transform defined by (resp. ). The computations are added to the queue to which desc was committed. Each process takes in the local chunk of the input, computes DFT on the data it is provided, exchanges the intermediate results using MPI, and provides the final local output chunk. Refer to data distribution on how the local input/output data is distributed across the processes.

Successive global computations require the distributed_descriptor objects across the processes be serialized to guarantee correct results. This can be done by waiting on the queue passed at commit, or by using an in-order queue. Alternatively, computations can be serialized using the returned syc::event and input dependencies.

The number of data-containing arguments to be provided depends exclusively on whether the desired DFT calculations are to be done in-place (output data overwriting the input data) or out-of-place (output data stored separately from the input data). One data-containing argument is required for in-place operations whereas two such arguments are needed for out-of-place calculations. Note that in-place operations require the global data layout to satisfy requirements documented in the page dedicated to configuring data layouts.

WARNING:

When using a function designed for in-place (resp. out-of-place) operations, desc (function’s first argument) must have a configuration value of oneapi::mkl::dft::config_value::INPLACE (resp. oneapi::mkl::dft::config_value::NOT_INPLACE) associated with oneapi::mkl::dft::config_param::PLACEMENT. And all the processes should be configured uniformly. The function’s behavior is undefined otherwise.
When using a function designed for out-of-place operations, in and out must not share common elements.
The sizes of the in and out must be greater than or equal to the queried sizes after commit.

Template parameters

For in-place operations

The compute_forward and compute_backward function templates for in-place operations are parameterized by two type template parameters, in the following order:

descriptor_type representing the type of desc, an instance of a specialization of the descriptor class template;
data_type representing the elementary data type of the data-containing argument being used.

The available specializations are listed in the table below.

Available specializations of the compute function templates for in-place operations.
function template	`descriptor_type`	`data_type`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::SINGLE, oneapi::mkl::dft::domain::REAL>`	`float`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::SINGLE, oneapi::mkl::dft::domain::REAL>`	`std::complex<float>`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::SINGLE, oneapi::mkl::dft::domain::COMPLEX>`	`float`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::SINGLE, oneapi::mkl::dft::domain::COMPLEX>`	`std::complex<float>`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::DOUBLE, oneapi::mkl::dft::domain::REAL>`	`double`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::DOUBLE, oneapi::mkl::dft::domain::REAL>`	`std::complex<double>`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::DOUBLE, oneapi::mkl::dft::domain::COMPLEX>`	`double`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::DOUBLE, oneapi::mkl::dft::domain::COMPLEX>`	`std::complex<double>`

For out-of-place operations

The compute_forward and compute_backward function templates for out-of-place operations are parameterized by three type template parameters, in the following order:

descriptor_type representing the type of desc, an instance of a specialization of the descriptor class template;
input_type representing the elementary data type of the first (input) data-containing argument being used;
output_type representing the elementary data type of the second (output) data-containing argument being used.

The available specializations are listed in the table below.

Available specializations of the compute function templates for out-of-place operations.
function template	`descriptor_type`	`input_type`	`output_type`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::SINGLE, oneapi::mkl::dft::domain::REAL>`	`float`	`float`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::SINGLE, oneapi::mkl::dft::domain::REAL>`	`std::complex<float>`	`std::complex<float>`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::SINGLE, oneapi::mkl::dft::domain::COMPLEX>`	`float`	`float`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::SINGLE, oneapi::mkl::dft::domain::COMPLEX>`	`std::complex<float>`	`std::complex<float>`
`compute_forward`	`distributed_descriptor<oneapi::mkl::dft::precision::SINGLE, oneapi::mkl::dft::domain::REAL>`	`float`	`std::complex<float>`
`compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::SINGLE, oneapi::mkl::dft::domain::REAL>`	`std::complex<float>`	`float`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::DOUBLE, oneapi::mkl::dft::domain::REAL>`	`double`	`double`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::DOUBLE, oneapi::mkl::dft::domain::REAL>`	`std::complex<double>`	`std::complex<double>`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::DOUBLE, oneapi::mkl::dft::domain::COMPLEX>`	`double`	`double`
`compute_forward` `compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::DOUBLE, oneapi::mkl::dft::domain::COMPLEX>`	`std::complex<double>`	`std::complex<double>`
`compute_forward`	`distributed_descriptor<oneapi::mkl::dft::precision::DOUBLE, oneapi::mkl::dft::domain::REAL>`	`double`	`std::complex<double>`
`compute_backward`	`distributed_descriptor<oneapi::mkl::dft::precision::DOUBLE, oneapi::mkl::dft::domain::REAL>`	`std::complex<double>`	`double`

Input parameters and returned value

The compute_forward and compute_backward template functions’ input parameters are documented below. These functions return a sycl::event object that can be used to track the completion of the computations that the function call enqueues.

For in-place operations

Input parameters for the in-place compute functions.
Name	Supported types	Description
`desc`	`descriptor_type`	Committed instance of a specialization of the distributed_descriptor class template, defining the global DFT to compute
`inout`	`data_type*`	Data-containing argument for the DFT (local input data on input, local output results on output)
`dependencies`	`std::vector<sycl::event>`	Vector of dependencies to be honored by the enqueued DFT computation

For out-of-place operations

Input parameters for the out-of-place compute functions.
Name	Supported types	Description
`desc`	`descriptor_type`	Committed instance of a specialization of the descriptor class template, defining the DFT to compute
`in`	`input_type*`	Data-containing argument for the local input data of the DFT
`out`	`output_type*`	Data-containing argument for the local output data of the DFT
`dependencies`	`std::vector<sycl::event>`	Vector of dependencies to be honored by the enqueued DFT computation

Exceptions

The compute_forward and compute_backward template functions may throw an oneapi::mkl::exception in the following cases:

an issue is found with desc.
desc is uncommitted.
a failure is detected when computing the DFT.
an MPI issues is detected when computing the DFT.

NOTE:

The distributed DFT interface does not support SYCL buffers.

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

oneMKL - Data Parallel C++ Developer Reference

Compute Functions

Description

Template parameters

Input parameters and returned value

Exceptions