.. _fourier-transform-functions: Fourier Transform Functions =========================== The general form of the discrete Fourier transform is: .. math:: Z_{(k_1, k_2, \ldots, k_d)} = \sigma \times \sum_{j_d = 0}^{n_d - 1} \ldots \sum_{j_2 = 0}^{n_2 - 1} \sum_{j_1 = 0}^{n_1 - 1} w_{j_1, j_2 \ldots j_d} \exp\left(\delta i 2 \pi \sum_{l=1}^d j_l k_l / n_l\right) for :math:`k_l = 0, \ldots n_l-1 (l = 1, \ldots, d)`, where ``σ`` is a scale factor, :math:`\delta = -1` for the forward transform, and :math:`\delta = +1` for the inverse (backward) transform. In the forward transform, the input (periodic) sequence :math:`\{w_{j1}, w_{j2}, \ldots, w_{jd}\}` belongs to the set of complex-valued sequences or the set of real-valued sequences, and the output sequence belongs to the set of complex-valued sequences or the set of complex-valued conjugate-even sequences, respectively. The |IONE-MKL| provides a DPC++ interface for computing a discrete Fourier transform through the fast Fourier transform algorithm. The DPC++ interface emulates the usage model of the |O-MKL| C and Fortran Discrete Fourier Transform Interface (DFTI). The DPC++ interface computes an FFT in four steps: 1. Allocate a fresh descriptor for the problem with a call to the descriptor object constructor, ``descriptor desc(dimensions);`` The descriptor captures the configuration of the transform, such as the dimensionality (or rank), sizes, number of transforms, memory layout of the input/output data (defined by strides), and scaling factors. Many of the configuration settings are assigned default values in this call which you might need to modify in your application. 2. Optionally adjust the descriptor configuration with a call to the ``descriptor::set_value`` function as needed. Typically, you must carefully define the data storage layout for an FFT. The configuration settings of the descriptor, such as the default values, can be obtained with the ``descriptor::get_value`` function. 3. Commit the descriptor with a call to the ``descriptor::commit`` function, that is, make the descriptor ready for the transform computation. Once the descriptor is committed, the parameters of the transform, such as the type and number of transforms, strides and distances, the type and storage layout of the data, and so on, are "frozen" in the descriptor. The commit function takes in a ``cl::sycl::queue`` object to determine the device associated with the descriptor. 4. Compute the transform with a call to the ``compute_forward`` or ``compute_backward`` functions as many times as needed. Because the descriptor is defined and committed separately, the compute functions just take the input and output data and compute the transform as defined. To modify any configuration parameters for another call to a compute function, use ``descriptor::set_value`` followed by ``descriptor::commit`` before calling the compute function again. All the above functions throw a named ``std::runtime_exception`` in the event of failure. To use the DPC++ interface, include ``oneapi/mkl/dfti.hpp``. The DPC++ interface supports host, CPU, and Intel GPU devices. Some functionality supported on the host device is not yet fully supported on Intel GPU devices. Some device-specific limitations are noted in the :ref:`descriptor-precision-domain-set_value` section of this document. Refer to the `Intel® oneAPI Math Kernel Library Release Notes `__ for known limitations. Working usage examples can be found in the |O-MKL| installation directory under ``examples/dpcpp/dft``. The FFT functions assume the Cartesian representation of complex data (that is, the real and imaginary parts define a complex number). The Intel® oneAPI Math Kernel Library Vector Mathematical Functions provide efficient tools for conversion to and from polar representation. See the `Conversion from Cartesian to polar representation of complex data `__ and `Conversion from polar to Cartesian representation of complex data `__ examples. .. toctree:: :maxdepth: 1 :hidden: descriptor-precision-domain descriptor-precision-domain-set_value descriptor-precision-domain-get_value descriptor-precision-domain-commit compute_fwd-typename-desc_type-typename_data_type compute_back-typenm-desc_type-typenm_data_type