diff --git a/source/elements/oneMKL/source/domains/dft/compute_backward.rst b/source/elements/oneMKL/source/domains/dft/compute_backward.rst index b27ed2dc3b..2065f4a606 100644 --- a/source/elements/oneMKL/source/domains/dft/compute_backward.rst +++ b/source/elements/oneMKL/source/domains/dft/compute_backward.rst @@ -4,378 +4,393 @@ .. _onemkl_dft_compute_backward: -compute_backward -================ +The ``compute_backward`` function templates +=========================================== -This function computes the backward DFT(s), as defined by an instantiation of -the :ref:`descriptor` class, on user-provided data. +The ``oneapi::mkl::dft::compute_backward`` function templates enable the +computation of backward DFT(s), as defined by a (committed) +``oneapi::mkl::dft::descriptor`` object, on user-provided data. These function +templates are declared in the ``oneapi::mkl::dft`` namespace; the usage of +prepended namespace specifiers ``oneapi::mkl::dft`` is omitted below for conciseness. .. _onemkl_dft_compute_backward_description: .. rubric:: Description -Given a successfully committed :ref:`descriptor` object -whose configuration is not inconsistent with backward DFT calculations, this -function computes the backward transform defined by that object. +Given a successfully-committed ``descriptor`` object whose configuration is not +inconsistent with backward DFT calculations, the backward DFT it defines can be +computed using a specialization of (some of) the ``compute_backward`` function +templates. -The ``compute_backward`` function requires a successfully committed object of -the :ref:`descriptor` class and one, two or four "data -container" arguments (depending on the configuration of the -:ref:`descriptor` object). If using (pointers to) USM -allocations as data containers, this function may also be provided with an +The ``compute_backward`` 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`` 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. +the desired DFT calculations and return a ``sycl::event`` instance tracking the +progress of the enqueued DFT calculations. .. note:: - The compute_backward function may need to access the internals and - private/protected members of the :ref:`descriptor` - class. This could be done, for instance, by labeling it as a friend function - to the :ref:`descriptor` class. + The ``compute_backward`` 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`` :ref:`class template`. .. onemkl_dft_compute_backward_buffer: -compute_backward (Buffer version) ---------------------------------- +``compute_backward`` (Buffer versions) +-------------------------------------- -.. rubric:: Syntax (in-place transform, except for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (in-place transform, except for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - void compute_backward( descriptor_type &desc, - sycl::buffer &inout); + void compute_backward(descriptor_type &desc, + sycl::buffer &inout); } -.. rubric:: Syntax (in-place transform, for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (in-place transform, for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - void compute_backward( descriptor_type &desc, - sycl::buffer &inout_re, - sycl::buffer &inout_im); + void compute_backward(descriptor_type &desc, + sycl::buffer &inout_re, + sycl::buffer &inout_im); } -.. rubric:: Syntax (out-of-place transform, except for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (out-of-place transform, except for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - void compute_backward( descriptor_type &desc, - sycl::buffer &in, - sycl::buffer &out); + void compute_backward(descriptor_type &desc, + sycl::buffer &in, + sycl::buffer &out); } -.. rubric:: Syntax (out-of-place transform, for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (out-of-place transform, for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - void compute_backward( descriptor_type &desc, - sycl::buffer &in_re, - sycl::buffer &in_im, - sycl::buffer &out_re, - sycl::buffer &out_im); + void compute_backward(descriptor_type &desc, + sycl::buffer &in_re, + sycl::buffer &in_im, + sycl::buffer &out_re, + sycl::buffer &out_im); } - .. container:: section .. rubric:: Input Parameters - :ref:`desc` - A fully configured and committed object of the - :ref:`descriptor` class, whose configuration is not - inconsistent with backward DFT calculations. + ``desc`` + A fully-configured and committed ``descriptor`` object, whose + configuration is not inconsistent with backward DFT calculations. - inout + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + (configured for in-place operations and not with ``config_value::REAL_REAL`` + for ``config_param::COMPLEX_STORAGE``, if complex). - inout_re + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + 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 + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 :ref:`onemkl_dft_complex_storage_real_real`. - + 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``. .. container:: section .. rubric:: Output Parameters - inout + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + (configured for in-place operations and not with ``config_value::REAL_REAL`` + for ``config_param::COMPLEX_STORAGE``, if complex). - inout_re + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``, if complex). - out_re + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + 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``. .. container:: section .. rubric:: 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: + The ``compute_backward`` functions shall throw the following + :ref:`exception` if the associated condition is + detected. An implementation may throw additional implementation-specific + exception(s) in case of error conditions not covered here: - :ref:`oneapi::mkl::invalid_argument()` - If the provided :ref:`descriptor` object ``desc`` - is invalid, for instance, if its configuration value associated with - configuration parameter ``config_param::COMMIT_STATUS`` is not - ``config_param::COMMITTED``. + ``oneapi::mkl::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``. .. onemkl_dft_compute_backward_usm: -compute_backward (USM version) ------------------------------- +``compute_backward`` (USM versions) +----------------------------------- -.. rubric:: Syntax (in-place transform, except for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (in-place transform, except for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - sycl::event compute_backward( descriptor_type &desc, - data_type *inout, - const std::vector &dependencies = {}); + sycl::event compute_backward(descriptor_type &desc, + data_type *inout, + const std::vector &dependencies = {}); } -.. rubric:: Syntax (in-place transform, for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (in-place transform, for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - sycl::event compute_backward( descriptor_type &desc, - data_type *inout_re, - data_type *inout_im, - const std::vector &dependencies = {}); + sycl::event compute_backward(descriptor_type &desc, + data_type *inout_re, + data_type *inout_im, + const std::vector &dependencies = {}); } -.. rubric:: Syntax (out-of-place transform, except for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (out-of-place transform, except for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - sycl::event compute_backward( descriptor_type &desc, - input_type *in, - output_type *out, - const std::vector &dependencies = {}); + sycl::event compute_backward(descriptor_type &desc, + input_type *in, + output_type *out, + const std::vector &dependencies = {}); } -.. rubric:: Syntax (out-of-place transform, for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (out-of-place transform, for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - 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 &dependencies = {}); + 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 &dependencies = {}); } .. container:: section .. rubric:: Input Parameters - :ref:`desc` - A fully configured and committed object of the - :ref:`descriptor` class, whose configuration is not - inconsistent with backward DFT calculations. + ``desc`` + A fully-configured and committed ``descriptor`` object, whose + configuration is not inconsistent with backward DFT calculations. - inout + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + (configured for in-place operations and not with ``config_value::REAL_REAL`` + for ``config_param::COMPLEX_STORAGE``, if complex). + - inout_re + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``, if complex). - in_re + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``dependencies`` An ``std::vector`` object collecting the events returned by - previously enqueued tasks that must be finished before this transform can - be calculated. + previously enqueued tasks that must be finished before the desired + transform can be calculated. .. container:: section .. rubric:: Output Parameters - inout + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + (configured for in-place operations and not with ``config_value::REAL_REAL`` + for ``config_param::COMPLEX_STORAGE``, if complex). - inout_re + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``, if complex). - out_re + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + 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``. .. container:: section .. rubric:: 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: + The ``compute_backward`` functions shall throw the following + :ref:`exception` if the associated condition is + detected. An implementation may throw additional implementation-specific + exception(s) in case of error conditions not covered here: - :ref:`oneapi::mkl::invalid_argument()` - If the provided :ref:`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 + ``oneapi::mkl::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``. .. container:: section .. rubric:: 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. + These functions return a ``sycl::event`` object that enables tracking + progress of the backward DFT, and that can be passed as a dependency to other + routines, which may depend on the result of the backward transform(s) before + proceeding with other operations. **Parent topic:** :ref:`onemkl_dft` diff --git a/source/elements/oneMKL/source/domains/dft/compute_forward.rst b/source/elements/oneMKL/source/domains/dft/compute_forward.rst index 009137056a..4543b18d5c 100644 --- a/source/elements/oneMKL/source/domains/dft/compute_forward.rst +++ b/source/elements/oneMKL/source/domains/dft/compute_forward.rst @@ -4,89 +4,92 @@ .. _onemkl_dft_compute_forward: -compute_forward -=============== +The ``compute_forward`` function templates +========================================== -This function computes the forward DFT(s), as defined by an instantiation of -the :ref:`descriptor` class, on user-provided data. +The ``oneapi::mkl::dft::compute_forward`` function templates enable the +computation of forward DFT(s), as defined by a (committed) +``oneapi::mkl::dft::descriptor`` object, on user-provided data. These function +templates are declared in the ``oneapi::mkl::dft`` namespace; the usage of +prepended namespace specifiers ``oneapi::mkl::dft`` is omitted below for conciseness. .. _onemkl_dft_compute_forward_description: .. rubric:: Description -Given a successfully committed :ref:`descriptor` object -whose configuration is not inconsistent with forward DFT calculations, this -function computes the forward transform defined by that object. +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`` function requires a successfully committed object of the -:ref:`descriptor` class and one, two or four "data -container" arguments (depending on the configuration of the -:ref:`descriptor` object). If using (pointers to) USM -allocations as data containers, this function may also be provided with an +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`` 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. +the desired DFT calculations and return a ``sycl::event`` instance tracking the +progress of the enqueued DFT calculations. .. note:: - The compute_forward function may need to access the internals and - private/protected members of the :ref:`descriptor` - class. This could be done, for instance, by labeling it as a friend function - to the :ref:`descriptor` class. + 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`` :ref:`class template`. .. onemkl_dft_compute_forward_buffer: -compute_forward (Buffer version) --------------------------------- +``compute_forward`` (Buffer versions) +------------------------------------- -.. rubric:: Syntax (in-place transform, except for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (in-place transform, except for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - void compute_forward( descriptor_type &desc, - sycl::buffer &inout); + void compute_forward(descriptor_type &desc, + sycl::buffer &inout); } -.. rubric:: Syntax (in-place transform, for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (in-place transform, for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - void compute_forward( descriptor_type &desc, - sycl::buffer &inout_re, - sycl::buffer &inout_im); + void compute_forward(descriptor_type &desc, + sycl::buffer &inout_re, + sycl::buffer &inout_im); } -.. rubric:: Syntax (out-of-place transform, except for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (out-of-place transform, except for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - void compute_forward( descriptor_type &desc, - sycl::buffer &in, - sycl::buffer &out); + void compute_forward(descriptor_type &desc, + sycl::buffer &in, + sycl::buffer &out); } -.. rubric:: Syntax (out-of-place transform, for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (out-of-place transform, for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - void compute_forward( descriptor_type &desc, - sycl::buffer &in_re, - sycl::buffer &in_im, - sycl::buffer &out_re, - sycl::buffer &out_im); + void compute_forward(descriptor_type &desc, + sycl::buffer &in_re, + sycl::buffer &in_im, + sycl::buffer &out_re, + sycl::buffer &out_im); } @@ -94,290 +97,301 @@ compute_forward (Buffer version) .. rubric:: Input Parameters - :ref:`desc` - A fully configured and committed object of the - :ref:`descriptor` class, whose configuration is not - inconsistent with forward DFT calculations. + ``desc`` + A fully-configured and committed ``descriptor`` object, whose + configuration is not inconsistent with forward DFT calculations. - inout + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + (configured for in-place operations and not with ``config_value::REAL_REAL`` + for ``config_param::COMPLEX_STORAGE``, if complex). - inout_re + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 :ref:`onemkl_dft_complex_storage_real_real`, if complex). + with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``, + if complex). - in_re + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + out-of-place operations with ``config_value::REAL_REAL`` for + ``config_param::COMPLEX_STORAGE``. - in_im + ``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 :ref:`onemkl_dft_complex_storage_real_real`. - + 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``. .. container:: section .. rubric:: Output Parameters - inout + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + (configured for in-place operations and not with ``config_value::REAL_REAL`` + for ``config_param::COMPLEX_STORAGE``, if complex). - inout_re + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``, if complex). - out_re + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + out-of-place operations with ``config_value::REAL_REAL`` for + ``config_param::COMPLEX_STORAGE``. - out_im + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + for out-of-place operations with ``config_value::REAL_REAL`` for + ``config_param::COMPLEX_STORAGE``. .. container:: section .. rubric:: 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: + The ``compute_forward`` functions shall throw the following + :ref:`exception` if the associated condition is + detected. An implementation may throw additional implementation-specific + exception(s) in case of error conditions not covered here: - :ref:`oneapi::mkl::invalid_argument()` - If the provided :ref:`descriptor` object ``desc`` - is invalid, for instance, if its configuration value associated with - configuration parameter ``config_param::COMMIT_STATUS`` is not - ``config_param::COMMITTED``. + ``oneapi::mkl::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``. .. onemkl_dft_compute_forward_usm: -compute_forward (USM version) ------------------------------ +``compute_forward`` (USM versions) +---------------------------------- -.. rubric:: Syntax (in-place transform, except for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (in-place transform, except for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - sycl::event compute_forward( descriptor_type &desc, - data_type *inout, - const std::vector &dependencies = {}); + sycl::event compute_forward(descriptor_type &desc, + data_type *inout, + const std::vector &dependencies = {}); } -.. rubric:: Syntax (in-place transform, for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (in-place transform, for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - sycl::event compute_forward( descriptor_type &desc, - data_type *inout_re, - data_type *inout_im, - const std::vector &dependencies = {}); + sycl::event compute_forward(descriptor_type &desc, + data_type *inout_re, + data_type *inout_im, + const std::vector &dependencies = {}); } -.. rubric:: Syntax (out-of-place transform, except for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (out-of-place transform, except for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - sycl::event compute_forward( descriptor_type &desc, - input_type *in, - output_type *out, - const std::vector &dependencies = {}); + sycl::event compute_forward(descriptor_type &desc, + input_type *in, + output_type *out, + const std::vector &dependencies = {}); } -.. rubric:: Syntax (out-of-place transform, for complex descriptors with :ref:`onemkl_dft_complex_storage_real_real`) +.. rubric:: Syntax (out-of-place transform, for complex descriptors with ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``) .. code-block:: cpp namespace oneapi::mkl::dft { template - 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 &dependencies = {}); + 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 &dependencies = {}); } .. container:: section .. rubric:: Input Parameters - :ref:`desc` - A fully configured and committed object of the - :ref:`descriptor` class, whose configuration is not - inconsistent with forward DFT calculations. + ``desc`` + A fully-configured and committed ``descriptor`` object, whose + configuration is not inconsistent with forward DFT calculations. - inout + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + (configured for in-place operations and not with ``config_value::REAL_REAL`` + for ``config_param::COMPLEX_STORAGE``, if complex). + - inout_re + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``, if complex). - in_re + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``dependencies`` An ``std::vector`` object collecting the events returned by - previously enqueued tasks that must be finished before this transform can - be calculated. + previously enqueued tasks that must be finished before the desired + transform can be calculated. .. container:: section .. rubric:: Output Parameters - inout + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + (configured for in-place operations and not with ``config_value::REAL_REAL`` + for ``config_param::COMPLEX_STORAGE``, if complex). - inout_re + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 - :ref:`onemkl_dft_complex_storage_real_real`, if complex). + ``config_value::REAL_REAL`` for ``config_param::COMPLEX_STORAGE``, if complex). - out_re + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + 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 + ``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 :ref:`onemkl_dft_complex_storage_real_real`. + 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``. .. container:: section .. rubric:: 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: + The ``compute_forward`` functions shall throw the following + :ref:`exception` if the associated condition is + detected. An implementation may throw additional implementation-specific + exception(s) in case of error conditions not covered here: - :ref:`oneapi::mkl::invalid_argument()` - If the provided :ref:`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 + ``oneapi::mkl::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``. .. container:: section .. rubric:: 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. + 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:** :ref:`onemkl_dft` diff --git a/source/elements/oneMKL/source/domains/dft/config_params/data_layouts.rst b/source/elements/oneMKL/source/domains/dft/config_params/data_layouts.rst index 17fa4343d8..9720aea80b 100644 --- a/source/elements/oneMKL/source/domains/dft/config_params/data_layouts.rst +++ b/source/elements/oneMKL/source/domains/dft/config_params/data_layouts.rst @@ -4,9 +4,12 @@ .. _onemkl_dft_config_data_layouts: -Configuration of Data Layouts +Configuration of data layouts ----------------------------- +The usage of prepended namespace specifiers ``oneapi::mkl::dft`` is +omitted below for conciseness. + The DFT interface provides the configuration parameters ``config_param::FWD_STRIDES`` (resp. ``config_param::BWD_STRIDES``) to define the data layout locating entries of relevant data sequences in the @@ -22,8 +25,8 @@ superscript :math:`\text{fwd}` (resp. :math:`\text{bwd}`) for data sequences belonging to forward (resp. backward) domain, for any :math:`m` and multi-index :math:`\left(k_1, k_2, \ldots, k_d\right)` within :ref:`valid range`, the corresponding entry -:math:`\left(\cdot\right)^{m}_{k_{1}, k_{2}, \dots, k_d }` - or the real or -imaginary part thereof - of the relevant data sequence is located at index +:math:`\left(\cdot\right)^{m}_{k_{1}, k_{2}, \dots, k_d }` – or the real or +imaginary part thereof – of the relevant data sequence is located at index .. math:: s^{\text{xwd}}_0 + k_1\ s^{\text{xwd}}_1 + k_2\ s^{\text{xwd}}_2 + \dots + k_d\ s^{\text{xwd}}_d + m\ l^{\text{xwd}} @@ -61,13 +64,13 @@ forward-domain (resp. backward-domain) data sequences and .. rubric:: Implicitly-assumed elementary data type When reading or writing an element at index :eq:`eq_idx_data_layout` of any -user-provided data container used at compute time, a -:ref:`descriptor` object may re-interpret the base data -type of that data container into an implicitly-assumed elementary data type. +user-provided data container used at compute time, a ``descriptor`` object may +re-interpret the base data type of that data container into an +implicitly-assumed elementary data type. That implicitly-assumed data type depends on the object type, *i.e.*, on the specialization values used for the template parameters when instantiating the -:ref:`descriptor` class, and, in case of complex -descriptors, on the configuration value set for its configuration parameter +``descriptor`` :ref:`class template`, and, in case of +complex descriptors, on the configuration value set for its configuration parameter ``config_param::COMPLEX_STORAGE``. The table below lists the implicitly-assumed data type in either domain (last 2 columns) based on the object type and its configuration value for ``config_param::COMPLEX_STORAGE`` (first 2 columns). @@ -213,26 +216,27 @@ configuration parameter ``config_param::INPUT_STRIDES`` if The values of :math:`s^{\text{i}}_{j}` and :math:`s^{\text{o}}_{j}` are to be used and considered by oneMKL if and only if :math:`s^{\text{fwd}}_{j} = s^{\text{bwd}}_{j} = 0, \forall j \in \lbrace 0, 1, \ldots, d\rbrace`. -(This will happen automatically if ``config_param::INPUT_STRIDES`` and ``config_param::OUTPUT_STRIDES`` -are set and ``config_param::FWD_STRIDES`` and ``config_param::BWD_STRIDES`` are not. See note below.) -In such a case, :ref:`descriptor` objects must consider -the data layouts corresponding to the two compute directions separately. As -detailed above, relevant data sequence entries are accessed as elements of data -containers (``sycl::buffer`` objects or device-accessible USM allocations) -provided to the compute function, the base data type of which is (possibly -implicitly re-interpreted) as documented in :ref:`this -table`. If using -input and output strides, for any :math:`m` and multi-index +This will happen automatically if ``config_param::INPUT_STRIDES`` and +``config_param::OUTPUT_STRIDES`` are set and ``config_param::FWD_STRIDES`` and +``config_param::BWD_STRIDES`` are not (see note below). +In such a case, ``descriptor`` objects must consider the data layouts +corresponding to the two compute directions separately. As detailed above, +relevant data sequence entries are accessed as elements of data containers +(``sycl::buffer`` objects or device-accessible USM allocations) provided to the +compute function, the base data type of which is (possibly implicitly re-interpreted) +as documented in the above +:ref:`table`. If +using input and output strides, for any :math:`m` and multi-index :math:`\left(k_1, k_2, \ldots, k_d\right)` within :ref:`valid range`, the index to be used when -accessing a data sequence entry - or part thereof - in forward domain is +accessing a data sequence entry – or part thereof – in forward domain is .. math:: s^{\text{x}}_0 + k_1\ s^{\text{x}}_1 + k_2\ s^{\text{x}}_2 + \dots + k_d\ s^{\text{x}}_d + m\ l^{\text{fwd}} where :math:`\text{x} = \text{i}` (resp. :math:`\text{x} = \text{o}`) for forward (resp. backward) DFT(s). Similarly, the index to be used when accessing -a data sequence entry - or part thereof - in backward domain is +a data sequence entry – or part thereof – in backward domain is .. math:: s^{\text{x}}_0 + k_1\ s^{\text{x}}_1 + k_2\ s^{\text{x}}_2 + \dots + k_d\ s^{\text{x}}_d + m\ l^{\text{bwd}} @@ -240,32 +244,31 @@ a data sequence entry - or part thereof - in backward domain is where :math:`\text{x} = \text{o}` (resp. :math:`\text{x} = \text{i}`) for forward (resp. backward) DFT(s). -As a consequence, configuring :ref:`descriptor` objects -using these deprecated configuration parameters makes their configuration -direction-dependent when different stride values are used in -forward and backward domains. Since the intended compute direction is unknown -to the :ref:`descriptor` object when +As a consequence, configuring ``descriptor`` objects using these deprecated +configuration parameters makes their configuration direction-dependent when +different stride values are used in forward and backward domains. Since the +intended compute direction is unknown to the object when :ref:`committing` it, every direction that results in a :ref:`consistent data layout` in -forward and backward domains must be supported by successfully committed -:ref:`descriptor` objects. +forward and backward domains must be supported by successfully-committed +``descriptor`` objects. .. note:: - For :ref:`descriptor` objects with strides configured - via these deprecated configuration parameters, the :ref:`consistency - requirements` may be satisfied for only - one of the two compute directions, *i.e.*, for only one of the forward or - backward DFT(s). Such a configuration should not cause an exception to be - thrown by the descriptor's :ref:`onemkl_dft_descriptor_commit` member - function but the behavior of oneMKL is undefined if using that object for - the compute direction that does not align with the :ref:`consistency - requirements`. + For ``descriptor`` objects with strides configured via these deprecated + configuration parameters, the + :ref:`consistency requirements` may be + satisfied for only one of the two compute directions, *i.e.*, for only one + of the forward or backward DFT(s). Such a configuration should not cause an + exception to be thrown by the descriptor's ``commit`` + :ref:`member function` but the behavior of + oneMKL is undefined if using that object for the compute direction that does + not align with the :ref:`consistency requirements`. .. note:: Setting either of ``config_param::INPUT_STRIDES`` or ``config_param::OUTPUT_STRIDES`` triggers any default or previously-set values for ``config_param::FWD_STRIDES`` and ``config_param::BWD_STRIDES`` - to reset to ``std::vector(d+1, 0)`` values, and vice versa. + to reset to ``std::vector(d+1, 0)``, and vice versa. This default behavior prevents mix-and-matching usage of either of ``config_param::INPUT_STRIDES`` or ``config_param::OUTPUT_STRIDES`` with either of ``config_param::FWD_STRIDES`` or ``config_param::BWD_STRIDES``, @@ -282,14 +285,15 @@ the reverse direction as shown below. .. code-block:: cpp + namespace dft = oneapi::mkl::dft; // ... - desc.set_value(config_param::INPUT_STRIDES, fwd_domain_strides); - desc.set_value(config_param::OUTPUT_STRIDES, bwd_domain_strides); + desc.set_value(dft::config_param::INPUT_STRIDES, fwd_domain_strides); + desc.set_value(dft::config_param::OUTPUT_STRIDES, bwd_domain_strides); desc.commit(queue); compute_forward(desc, ...); // ... - desc.set_value(config_param::INPUT_STRIDES, bwd_domain_strides); - desc.set_value(config_param::OUTPUT_STRIDES, fwd_domain_strides); + desc.set_value(dft::config_param::INPUT_STRIDES, bwd_domain_strides); + desc.set_value(dft::config_param::OUTPUT_STRIDES, fwd_domain_strides); desc.commit(queue); compute_backward(desc, ...); diff --git a/source/elements/oneMKL/source/domains/dft/config_params/storage_formats.rst b/source/elements/oneMKL/source/domains/dft/config_params/storage_formats.rst index 0dfdf214af..7a8dfcdaea 100644 --- a/source/elements/oneMKL/source/domains/dft/config_params/storage_formats.rst +++ b/source/elements/oneMKL/source/domains/dft/config_params/storage_formats.rst @@ -7,10 +7,13 @@ Data storage ============ -The data storage convention observed by a -:ref:`descriptor` object depends on whether it is a real -or complex descriptor and, in case of complex descriptors, on the configuration -value associated with configuration parameter ``config_param::COMPLEX_STORAGE``. +The usage of prepended namespace specifiers ``oneapi::mkl::dft`` is +omitted below for conciseness. + +The data storage convention observed by a ``descriptor`` object depends on +whether it is a real or complex descriptor and, in case of complex descriptors, +on the configuration value associated with configuration parameter +``config_param::COMPLEX_STORAGE``. .. _onemkl_dft_complex_storage: @@ -24,14 +27,12 @@ associated with a configuration value ``config_value::COMPLEX_COMPLEX`` (default behavior), those entries are accessed and stored as ``std::complex`` (resp. ``std::complex``) elements of a single data container (device-accessible USM allocation or ``sycl::buffer`` object) if the -:ref:`descriptor` object is a single-precision (resp. -double-precision) descriptor. If the configuration value -``config_value::REAL_REAL`` is used instead, the real and imaginary parts of -those entries are accessed and stored as ``float`` (resp. ``double``) elements -of two separate, non-overlapping data containers (device-accessible USM -allocations or ``sycl::buffer`` objects) if the -:ref:`descriptor` object is a single-precision (resp. -double-precision) descriptor. +``descriptor`` object is a single-precision (resp. double-precision) descriptor. +If the configuration value ``config_value::REAL_REAL`` is used instead, the real +and imaginary parts of those entries are accessed and stored as ``float`` (resp. +``double``) elements of two separate, non-overlapping data containers +(device-accessible USM allocations or ``sycl::buffer`` objects) if the +``descriptor`` object is a single-precision (resp. double-precision) descriptor. These two behaviors are further specified and illustrated below. @@ -45,20 +46,19 @@ sequences must belong to a single data container (device-accessible USM allocation or ``sycl::buffer`` object). Any relevant entry :math:`\left(\cdot\right)^{m}_{k_1, k_2,\dots ,k_d}` is accessed/stored from/in a data container provided at compute time at the index value expressed in eq. -:eq:`eq_idx_data_layout` (from :ref:`this page`) +:eq:`eq_idx_data_layout` (see the page dedicated to the +:ref:`configuration of data layout`) of that data container, whose elementary data type is (possibly implicitly re-interpreted as) ``std::complex`` (resp. ``std::complex``) for single-precision (resp. double-precision) descriptors. The same unique data container is to be used for forward- and backward-domain -data sequences for in-place transforms (for -:ref:`descriptor` objects with configuration value -``config_value::INPLACE`` for configuration parameter +data sequences for in-place transforms (for ``descriptor`` objects with +configuration value ``config_value::INPLACE`` for configuration parameter ``config_param::PLACEMENT``). Two separate data containers sharing no common -elements are to be used for out-of-place transforms (for -:ref:`descriptor` objects with configuration value -``config_value::NOT_INPLACE`` for configuration parameter -``config_param::PLACEMENT``). +elements are to be used for out-of-place transforms (for ``descriptor`` objects +with configuration value ``config_value::NOT_INPLACE`` for configuration +parameter ``config_param::PLACEMENT``). The following snippet illustrates the usage of ``config_value::COMPLEX_COMPLEX`` for configuration parameter ``config_param::COMPLEX_STORAGE``, in the @@ -84,8 +84,8 @@ USM allocations. // initialize forward-domain data such that entry {m;k1,k2,k3} // = Z[ strides[0] + k1*strides[1] + k2*strides[2] + k3*strides[3] + m*dist ] - compute_forward(desc, Z); // complex-to-complex in-place DFT - // in backward domain: entry {m;k1,k2,k3} + auto ev = compute_forward(desc, Z); // complex-to-complex in-place DFT + // Upon completion of ev, in backward domain: entry {m;k1,k2,k3} // = Z[ strides[0] + k1*strides[1] + k2*strides[2] + k3*strides[3] + m*dist ] .. _onemkl_dft_complex_storage_real_real: @@ -98,21 +98,20 @@ read/stored from/in two different, non-overlapping data containers (device-accessible USM allocations or ``sycl::buffer`` objects) encapsulating the real and imaginary parts of the relevant entries separately. The real and imaginary parts of any relevant complex entry -:math:`\left(\cdot\right)^{m}_{k_1, k_2,\dots ,k_d}` are both stored at the index value -expressed in eq. :eq:`eq_idx_data_layout` (from :ref:`this -page`) of their respective data containers, whose elementary -data type is (possibly implicitly re-interpreted as) ``float`` (resp. -``double``) for single-precision (resp. double-precision) descriptors. +:math:`\left(\cdot\right)^{m}_{k_1, k_2,\dots ,k_d}` are both stored at the +index value expressed in eq. :eq:`eq_idx_data_layout` (see the page dedicated to +the :ref:`configuration of data layout`) of +their respective data containers, whose elementary data type is (possibly +implicitly re-interpreted as) ``float`` (resp. ``double``) for single-precision +(resp. double-precision) descriptors. The same two data containers are to be used for real and imaginary parts of forward- and backward-domain data sequences for in-place transforms (for -:ref:`descriptor` objects with configuration value -``config_value::INPLACE`` for configuration parameter -``config_param::PLACEMENT``). Four separate data containers sharing no common -elements are to be used for out-of-place transforms (for -:ref:`descriptor` objects with configuration value -``config_value::NOT_INPLACE`` for configuration parameter -``config_param::PLACEMENT``). +``descriptor`` objects with configuration value ``config_value::INPLACE`` for +configuration parameter ``config_param::PLACEMENT``). Four separate data +containers sharing no common elements are to be used for out-of-place transforms +(for ``descriptor`` objects with configuration value ``config_value::NOT_INPLACE`` +for configuration parameter ``config_param::PLACEMENT``). The following snippet illustrates the usage of ``config_value::REAL_REAL`` set for configuration parameter ``config_param::COMPLEX_STORAGE``, in the @@ -141,8 +140,8 @@ USM allocations. // = ZR[ strides[0] + k1*strides[1] + k2*strides[2] + k3*strides[3] + m*dist ] // and the imaginary part of entry {m;k1,k2,k3} // = ZI[ strides[0] + k1*strides[1] + k2*strides[2] + k3*strides[3] + m*dist ] - compute_forward(desc, ZR, ZI); // complex-to-complex in-place DFT - // in backward domain: the real part of entry {m;k1,k2,k3} + auto ev = compute_forward(desc, ZR, ZI); // complex-to-complex in-place DFT + // Upon completion of ev, in backward domain: the real part of entry {m;k1,k2,k3} // = ZR[ strides[0] + k1*strides[1] + k2*strides[2] + k3*strides[3] + m*dist ] // and the imaginary part of entry {m;k1,k2,k3} // = ZI[ strides[0] + k1*strides[1] + k2*strides[2] + k3*strides[3] + m*dist ] @@ -156,14 +155,13 @@ Real descriptors observe only one type of data storage. Any relevant (real) entry :math:`\left(\cdot\right)^{m}_{k_1, k_2,\dots ,k_d}` of a data sequence in forward domain is accessed and stored as a ``float`` (resp. ``double``) element of a single data container (device-accessible USM allocation or -``sycl::buffer`` object) if the :ref:`descriptor` object -is a single-precision (resp. double-precision) descriptor. Any relevant -(complex) entry :math:`\left(\cdot\right)^{m}_{k_1, k_2,\dots ,k_d}` of a data -sequence in backward domain is accessed and stored as a ``std::complex`` -(resp. ``std::complex``) element of a single data container -(device-accessible USM allocation or ``sycl::buffer`` object) if the -:ref:`descriptor` object is a single-precision (resp. -double-precision) descriptor. +``sycl::buffer`` object) if the ``descriptor`` object is a single-precision +(resp. double-precision) descriptor. Any relevant (complex) entry +:math:`\left(\cdot\right)^{m}_{k_1, k_2,\dots ,k_d}` of a data sequence in +backward domain is accessed and stored as a ``std::complex`` (resp. +``std::complex``) element of a single data container (device-accessible +USM allocation or ``sycl::buffer`` object) if the +``descriptor`` object is a single-precision (resp. double-precision) descriptor. The following snippet illustrates the usage of a real, single-precision descriptor (and the corresponding data storage) for the in-place, @@ -190,12 +188,13 @@ forward and backward domains, with USM allocations. // initialize forward-domain data such that real entry {m;k1,k2,k3} // = data[ fwd_strides[0] + k1*fwd_strides[1] + k2*fwd_strides[2] + k3*fwd_strides[3] + m*fwd_dist ] - compute_forward(desc, data); // real-to-complex in-place DFT - // in backward domain, the implicitly-assumed type is complex so, considering + auto ev = compute_forward(desc, data); // real-to-complex in-place DFT + // In backward domain, the implicitly-assumed type is complex so, consider // std::complex* complex_data = static_cast*>(data); - // we have entry {m;k1,k2,k3} + // upon completion of ev, the backward-domain entry {m;k1,k2,k3} is // = complex_data[ bwd_strides[0] + k1*bwd_strides[1] + k2*bwd_strides[2] + k3*bwd_strides[3] + m*bwd_dist ] // for 0 <= k3 <= n3/2. - // Note: if n3/2 < k3 < n3, entry {m;k1,k2,k3} = std::conj(entry {m;n1-k1,n2-k2,n3-k3}) + // Note: if n3/2 < k3 < n3, entry {m;k1,k2,k3} is not stored explicitly + // since it is equal to std::conj(entry {m;n1-k1,n2-k2,n3-k3}) **Parent topic** :ref:`onemkl_dft_enums` diff --git a/source/elements/oneMKL/source/domains/dft/config_params/workspace_placement.rst b/source/elements/oneMKL/source/domains/dft/config_params/workspace_placement.rst index 4f73e91da6..d187810fe6 100644 --- a/source/elements/oneMKL/source/domains/dft/config_params/workspace_placement.rst +++ b/source/elements/oneMKL/source/domains/dft/config_params/workspace_placement.rst @@ -5,30 +5,40 @@ .. _onemkl_dft_config_workspace_placement: Workspace placement --------------------------------------- +------------------- + +The usage of prepended namespace specifiers ``oneapi::mkl::dft`` is +omitted below for conciseness. DFT implementations often require temporary storage for intermediate data whilst computing DFTs. This temporary storage is referred to as a *workspace*. -Whilst this is managed automatically by default (``config_value::WORKSPACE_AUTOMATIC`` -set for ``config_param::WORKSPACE_PLACEMENT``), it may be preferable to provide an external -workspace (``config_value::WORKSPACE_EXTERNAL`` set for ``config_param::WORKSPACE_PLACEMENT``) +Whilst ``descriptor`` objects manage their own workspace automatically by default +(``config_value::WORKSPACE_AUTOMATIC`` set for ``config_param::WORKSPACE_PLACEMENT``), +it may be preferable to provide them with an external workspace +(``config_value::WORKSPACE_EXTERNAL`` set for ``config_param::WORKSPACE_PLACEMENT``) for the following reasons: * to reduce the number of mallocs / frees; * to reduce memory consumption. -For some backends and configurations, ``config_value::WORKSPACE_EXTERNAL`` may reduce performance. +For some backends and configurations, externally-managed workspaces may reduce +performance. -A typical workflow for using ``config_value::WORKSPACE_EXTERNAL`` is given in the section :ref:`below`. +A typical workflow for using externally-managed workspaces is given +:ref:`below`. -WORKSPACE_PLACEMENT -+++++++++++++++++++ +Automatically- and externally-managed workspaces +++++++++++++++++++++++++++++++++++++++++++++++++ -For ``config_param::WORKSPACE_PLACEMENT``, valid configuration values are ``config_value::WORKSPACE_AUTOMATIC`` and ``config_value::WORKSPACE_EXTERNAL``. +For any ``descriptor`` object, its configuration value associated with +configuration parameter ``config_param::WORKSPACE_PLACEMENT`` determines whether +it manages its workspace automatically (configuration value +``config_value::WORKSPACE_AUTOMATIC``) or if it is to be provided with an +external workspace (configuration value ``config_value::WORKSPACE_EXTERNAL``). .. _onemkl_dft_config_value_workspace_automatic: -.. rubric:: WORKSPACE_AUTOMATIC +.. rubric:: Automatically-managed workspace The default value for the ``config_param::WORKSPACE_PLACEMENT`` is ``config_value::WORKSPACE_AUTOMATIC``. @@ -36,24 +46,27 @@ When set to ``config_value::WORKSPACE_AUTOMATIC`` the user does not need to prov .. _onemkl_dft_config_value_workspace_external: -.. rubric:: WORKSPACE_EXTERNAL +.. rubric:: Externally-managed workspace -The configuration ``config_param::WORKSPACE_PLACEMENT`` can be set to +The configuration parameter ``config_param::WORKSPACE_PLACEMENT`` can be set to ``config_value::WORKSPACE_EXTERNAL`` to allow the workspace to be set manually. When a descriptor is committed with ``config_value::WORKSPACE_EXTERNAL`` set for ``config_param::WORKSPACE_PLACEMENT``, the user must provide an external workspace before calling any compute function. -See :ref:`onemkl_dft_descriptor_set_workspace` and :ref:`onemkl_dft_typical_usage_of_workspace_external`. +More details can be found in the section dedicated to the ``set_workspace`` +:ref:`member function` and in the typical +usage illustrated :ref:`below`. .. _onemkl_dft_typical_usage_of_workspace_external: -Typical usage of ``WORKSPACE_EXTERNAL`` -+++++++++++++++++++++++++++++++++++++++ +Typical usage of externally-managed workspaces +++++++++++++++++++++++++++++++++++++++++++++++ -Usage of ``config_value::WORKSPACE_EXTERNAL`` typically involves the following order of operations: +The usage of ``config_value::WORKSPACE_EXTERNAL`` typically involves the +following order of operations: -#. ``config_value::WORKSPACE_EXTERNAL`` is set for the uncommitted descriptor's ``config_param::WORKSPACE_EXTERNAL``. +#. ``config_value::WORKSPACE_EXTERNAL`` is set for the uncommitted descriptor's ``config_param::WORKSPACE_PLACEMENT``. #. The descriptor is committed. #. The required workspace size is queried. #. A workspace of sufficient size is provided to the descriptor. @@ -64,18 +77,19 @@ This is shown in the following example code: .. code-block:: cpp + namespace dft = oneapi::mkl::dft; // Create a descriptor - mkl::dft::descriptor desc(n); + dft::descriptor desc(n); // 1. Set the workspace placement to WORKSPACE_EXTERNAL - desc.set_value(mkl::dft::config_param::WORKSPACE_PLACEMENT, - mkl::dft::config_value::WORKSPACE_EXTERNAL); + desc.set_value(dft::config_param::WORKSPACE_PLACEMENT, + dft::config_value::WORKSPACE_EXTERNAL); // Set further configuration parameters // ... // 2. Commit the descriptor desc.commit(myQueue); // 3. Query the required workspace size std::int64_t workspaceBytes{0}; - desc.get_value(mkl::dft::config_param::WORKSPACE_EXTERNAL_BYTES, &workspaceBytes); + desc.get_value(dft::config_param::WORKSPACE_EXTERNAL_BYTES, &workspaceBytes); // Obtain a sufficiently large USM allocation or buffer. For this example, a USM allocation is used. float* workspaceUsm = sycl::malloc_device(workspaceBytes / sizeof(float), myQueue); // 4. Set the workspace diff --git a/source/elements/oneMKL/source/domains/dft/descriptor.rst b/source/elements/oneMKL/source/domains/dft/descriptor.rst index 27cb505c8d..2cdd7f8130 100644 --- a/source/elements/oneMKL/source/domains/dft/descriptor.rst +++ b/source/elements/oneMKL/source/domains/dft/descriptor.rst @@ -4,55 +4,54 @@ .. _onemkl_dft_descriptor: -The ``descriptor`` class -======================== +The ``descriptor`` class template +================================= -Objects of the ``descriptor`` class define DFT(s) to be computed. +Instances of any ``oneapi::mkl::dft::descriptor`` class define DFT(s) to be +computed. The usage of prepended namespace specifiers ``oneapi::mkl::dft`` is +omitted below for conciseness. -.. rubric:: Description +Description ++++++++++++ -Any desired (batched) DFT is to be fully determined by an object of the -``oneapi::mkl::dft::descriptor`` class, defined in the ``oneapi::mkl::dft`` -namespace. The scoped enumeration types :ref:`onemkl_dft_enum_precision`, -:ref:`onemkl_dft_enum_domain`, :ref:`onemkl_dft_enum_config_param` and -:ref:`onemkl_dft_enum_config_value` defined in the same namespace (and the +Any desired DFT is fully defined by an instance of a specialization of the +``descriptor`` class template, declared in the ``oneapi::mkl::dft`` namespace. +The :ref:`scoped enumeration types` ``precision``, ``domain``, +``config_param`` and ``config_value`` defined in the same namespace (and the corresponding ranges of values) are relevant to the definition and -configurations of objects of the ``descriptor`` class. The ``descriptor`` class -allows the user to set several (resp. query all) configuration parameters for (resp. -from) any of its instances by using their -:ref:`onemkl_dft_descriptor_set_value` (resp. -:ref:`onemkl_dft_descriptor_get_value`) member function. - -Invoking the member function :ref:`onemkl_dft_descriptor_commit` of an object of -the ``descriptor`` class effectively commits that object to the desired DFT -calculations, as configured and determined by that very object, on the specified +configurations of such objects. Users can set several (resp. query all) +configuration parameters for (resp. from) any ``descriptor`` object by using +its ``set_value`` (resp. ``get_value``) member functions. + +Invoking the ``commit`` member function of a ``descriptor`` object effectively +commits it to the desired DFT calculations (as it defines it) on the specific device encapsulated by the ``sycl::queue`` object required by that function. The desired forward (resp. backward) DFT calculations may then be computed by -passing such a committed ``descriptor`` object to the -:ref:`onemkl_dft_compute_forward` (resp. :ref:`onemkl_dft_compute_backward`) -function (defined in the ``oneapi::mkl::dft`` namespace as well), along with the -relevant data containers (``sycl::buffer`` object(s) or pointer(s) to a -device-accessible USM allocations) for the desired DFT(s). This function makes -the ``descriptor`` object enqueue the operations relevant for the desired -calculations to the ``sycl::queue`` object it was given when committing it. +passing such a committed ``descriptor`` object to a ``compute_forward`` (resp. +``compute_backward``) function (defined in the ``oneapi::mkl::dft`` namespace as +well), along with the relevant data containers (``sycl::buffer`` object(s) or +pointer(s) to a device-accessible USM allocations) for the desired DFT(s). This +function makes the ``descriptor`` object enqueue the operations relevant for the +desired calculations to the ``sycl::queue`` object it was given when committing it. .. note:: - The :ref:`onemkl_dft_compute_forward` and :ref:`onemkl_dft_compute_backward` - functions may need to be able to access the internals of the ``descriptor`` - object to compute the desired transform(s), this could be done for instance, - by labeling them as friend functions of the ``descriptor`` class. + The ``compute_forward`` and ``compute_backward`` functions may need to be + able to access the internals of the ``descriptor`` object to compute the + desired transform(s), this could be done for instance, by labeling them as + friend functions of the ``descriptor`` class template. .. rubric:: Syntax -The ``descriptor`` class is defined in the ``oneapi::mkl::dft`` namespace. - .. code-block:: cpp namespace oneapi::mkl::dft { - template + template class descriptor { + private: + using real_scalar_t = std::conditional_t; + public: // Constructor for 1-dimensional DFT @@ -70,50 +69,66 @@ The ``descriptor`` class is defined in the ``oneapi::mkl::dft`` namespace. descriptor& operator=(descriptor&&); ~descriptor(); - - - void set_value(oneapi::mkl::dft::config_param param, ...); - - void get_value(oneapi::mkl::dft::config_param param, ...); + + void set_value(config_param param, config_value value); + void set_value(config_param param, std::int64_t value); + void set_value(config_param param, real_scalar_t value); + [[deprecated("Use set_value(config_param, const std::vector&) instead.")]] + void set_value(config_param param, const std::int64_t* value); + void set_value(config_param param, const std::vector& value); + template , bool> = true> + void set_value(config_param param, T value) { + set_value(param, static_cast(value)); + } + template , bool> = true> + void set_value(config_param param, T value) { + set_value(param, static_cast(value)); + } + [[deprecated("This set_value member function is deprecated.")]] + void set_value(config_param param, ...); + + void get_value(config_param param, config_value* value_ptr) const; + void get_value(config_param param, domain* value_ptr) const; + void get_value(config_param param, precision* value_ptr) const; + void get_value(config_param param, std::int64_t* value_ptr) const; + void get_value(config_param param, real_scalar_t* value_ptr) const; + void get_value(config_param param, std::vector* value_ptr) const; + [[deprecated("This get_value member function is deprecated.")]] + void get_value(config_param param, ...) const; - void set_workspace(sycl::buffer &workspaceBuf); - void set_workspace(scalar_type* workspaceUSM); + void set_workspace(sycl::buffer &workspaceBuf); + void set_workspace(real_scalar_t* workspaceUSM); void commit(sycl::queue &queue); }; - - } - .. _onemkl_dft_descriptor_template_parameters: -.. rubric:: Descriptor class template parameters - -:ref:`onemkl_dft_enum_precision` prec - Specifies the floating-point precision in which the user-provided data is to - be provided, the transform is to be carried out and the results are to be - returned. The possible specialization values are - ``oneapi::mkl::dft::precision::SINGLE`` and - ``oneapi::mkl::dft::precision::DOUBLE``. Objects of the ``descriptor`` class - specialized with :ref:`onemkl_dft_enum_precision` template parameter ``prec`` - as value ``oneapi::mkl::dft::precision::SINGLE`` (resp. - ``oneapi::mkl::dft::precision::DOUBLE``) are referred to as "single-precision +.. rubric:: Template parameters + +``precision prec`` + Specifies the floating-point format of the user-provided data, the results, + and the precision of the floating-point operations to be enqueued. The + possible specialization values are ``precision::SINGLE`` and + ``precision::DOUBLE``, corresponding to single-precision (FP32) and + double-precision (FP64) floating-point formats, respectively . Objects of a + ``descriptor`` class specialized with ``precision::SINGLE`` (resp. + ``precision::DOUBLE``) as ``prec`` are referred to as "single-precision descriptors" (resp. "double-precision descriptors"). -:ref:`onemkl_dft_enum_domain` dom - Specifies the forward domain of the transform. The possible specialization - values are ``oneapi::mkl::dft::domain::COMPLEX`` and - ``oneapi::mkl::dft::domain::REAL``. Objects of the ``descriptor`` class - specialized with :ref:`onemkl_dft_enum_domain` template parameter ``dom`` as - value ``oneapi::mkl::dft::precision::COMPLEX`` (resp. - ``oneapi::mkl::dft::precision::REAL``) are referred to as "complex - descriptors" (resp. "real descriptors"). +``domain dom`` + Specifies the type of forward domain for the transform. The possible + specialization values are ``domain::COMPLEX`` and ``domain::REAL``, + corresponding to complex and real forward domains, respectively. Objects of + the ``descriptor`` class specialized with ``domain::COMPLEX`` (resp. + ``domain::REAL``) as ``dom`` are referred to as "complex descriptors" (resp. + "real descriptors"). .. _onemkl_dft_descriptor_member_table: -.. rubric:: Descriptor class member functions +.. rubric:: Member functions of the ``descriptor`` class template .. list-table:: :header-rows: 1 @@ -121,62 +136,66 @@ The ``descriptor`` class is defined in the ``oneapi::mkl::dft`` namespace. * - Routines - Description - * - :ref:`constructors` - - Creates and default-initializes a ``descriptor`` object for a - :math:`d`-dimensional DFT of user-defined length(s) - :math:`\lbrace n_1, \ldots, n_d\rbrace`. - * - :ref:`assignment operators` - - Performs a deep copy of or moves the argument. - * - :ref:`onemkl_dft_descriptor_set_value` - - Sets a configuration value for a specific configuration parameter. - * - :ref:`onemkl_dft_descriptor_get_value` - - Queries the configuration value associated with a particular + * - :ref:`constructors` + - Create a ``descriptor`` object. The parameterized constructors + enable the (one-time) definition of the length(s) + :math:`\lbrace n_1, \ldots, n_d\rbrace` (the dimension :math:`d` is + deduced accordingly). The parameterized constructors default-initialize + the object; copy and move constructors do not. + * - :ref:`assignment operators` + - Perform a deep copy of or moves the argument. + * - ``set_value`` :ref:`member functions` + - Set a configuration value for a specific configuration parameter. + * - ``get_value`` :ref:`member functions` + - Query the configuration value associated with a particular configuration parameter. - * - :ref:`onemkl_dft_descriptor_set_workspace` - - Sets the external workspace to use when ``config_param::WORKSPACE_PLACEMENT`` is set to ``config_value::WORKSPACE_EXTERNAL``. - * - :ref:`onemkl_dft_descriptor_commit` + * - ``set_workspace`` :ref:`member function` + - Equips the ``descriptor`` object with an external workspace. + * - ``commit`` :ref:`member function` - Commits the ``descriptor`` object to enqueue the operations relevant - to the (batched) DFT(s) it determines to a given, user-provided - ``sycl::queue`` object; completes all initialization work relevant to - and required by the chosen, device-compliant implementation for the - particular DFT, as defined by the ``descriptor`` object. + to the DFT(s) it determines to a given, user-provided ``sycl::queue`` + object; completes all initialization work relevant to and required by + the chosen, device-compliant implementation for the particular DFT, + as defined by the ``descriptor`` object. -.. _onemkl_dft_descriptor_constructor: +.. _onemkl_dft_descriptor_constructors: -Descriptor class constructors -++++++++++++++++++++++++++++++ +Constructors +++++++++++++ -The constructors for the ``descriptor`` object instantiate -it with all the relevant default configuration settings (which may depend on the -specialization values used for the :ref:`onemkl_dft_enum_precision` template -parameter ``prec`` and for the :ref:`onemkl_dft_enum_domain` template parameter -``dom``). The constructors do not perform any significant initialization work as -changes in the object's configuration(s) may be operated thereafter (via its -:ref:`onemkl_dft_descriptor_set_value` member function) and modify significantly -the nature of that work. +The parameterized constructors for a ``descriptor`` object instantiate it with +all the relevant default configuration settings (which may depend on the +specialization values for ``prec`` and ``dom``). The constructors do not perform +any significant initialization work as changes in the object's configuration(s) +may be operated thereafter (via its ``set_value`` +:ref:`member functions`) and modify +significantly the nature of that work. The copy constructor performs a deep copy of ``descriptor`` objects. -.. rubric:: Syntax (one-dimensional transform) +The move constructor transfers the resources owned by a ``descriptor`` object, +without copying them. + +.. rubric:: Parameterized constructor (one-dimensional transform) .. code-block:: cpp namespace oneapi::mkl::dft { - template - descriptor(std::int64_t length); + template + descriptor::descriptor(std::int64_t length); } -.. rubric:: Syntax (:math:`d`-dimensional transform with :math:`d > 0`) +.. rubric:: Parameterized constructor (transform of any dimension) .. code-block:: cpp namespace oneapi::mkl::dft { - template - descriptor(std::vector lengths); + template + descriptor::descriptor(std::vector lengths); } @@ -186,8 +205,8 @@ The copy constructor performs a deep copy of ``descriptor`` objects. namespace oneapi::mkl::dft { - template - descriptor(const descriptor& other); + template + descriptor::descriptor(const descriptor& other); } @@ -197,8 +216,8 @@ The copy constructor performs a deep copy of ``descriptor`` objects. namespace oneapi::mkl::dft { - template - descriptor(descriptor&& other); + template + descriptor::descriptor(descriptor&& other); } @@ -207,44 +226,44 @@ The copy constructor performs a deep copy of ``descriptor`` objects. .. rubric:: Input Parameters - length + ``length`` Length :math:`n_1 > 0` of the data sequence(s) for one-dimensional transform(s). - lengths + ``lengths`` Vector of :math:`d > 0` lengths :math:`\lbrace n_1, \ldots, n_d\rbrace` of the data sequence(s) for :math:`d`-dimensional transform(s). The values are to be provided in that order and such that :math:`n_j > 0,\ \forall j \in \lbrace 1, \ldots, d \rbrace`. - other + ``other`` Another ``descriptor`` object of the same type to copy or move. .. container:: section .. rubric:: Throws - The ``descriptor::descriptor()`` constructors 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: + The constructors shall throw the following + :ref:`exceptions` if the associated condition is + detected. An implementation may throw additional implementation-specific + exception(s) in case of error conditions not covered here: - :ref:`oneapi::mkl::host_bad_alloc()` + ``oneapi::mkl::host_bad_alloc()`` If any memory allocations on host have failed, for instance due to insufficient memory. - :ref:`oneapi::mkl::unimplemented()` - If the dimension :math:`d`, *i.e.*, the size of vector ``lengths``, is - larger than what is supported by the library implementation. + ``oneapi::mkl::unimplemented()`` + If the dimension :math:`d`, *i.e.*, the size of ``lengths``, is larger + than what is supported by the library implementation. **Descriptor class member table:** :ref:`onemkl_dft_descriptor_member_table` -.. _onemkl_dft_descriptor_assignment_operator: +.. _onemkl_dft_descriptor_assignment_operators: -Descriptor class assignment operators -+++++++++++++++++++++++++++++++++++++ +Assignment operators +++++++++++++++++++++ The copy assignment operator results in a deep copy. @@ -254,7 +273,7 @@ The copy assignment operator results in a deep copy. namespace oneapi::mkl::dft { - template + template descriptor& descriptor::operator=(const descriptor& other); } @@ -265,7 +284,7 @@ The copy assignment operator results in a deep copy. namespace oneapi::mkl::dft { - template + template descriptor& descriptor::operator=(descriptor&& other); } @@ -275,19 +294,19 @@ The copy assignment operator results in a deep copy. .. rubric:: Input Parameters - other - The ``descriptor`` object to copy or move from. + ``other`` + Another ``descriptor`` object to copy or move from. .. container:: section .. rubric:: Throws - The assignment operators 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: + The assignment operators shall throw the following + :ref:`exception` if the associated condition is + detected. An implementation may throw additional implementation-specific + exception(s) in case of error conditions not covered here: - :ref:`oneapi::mkl::host_bad_alloc()` + ``oneapi::mkl::host_bad_alloc()`` If any memory allocations on host have failed, for instance due to insufficient memory. @@ -295,151 +314,410 @@ The copy assignment operator results in a deep copy. .. _onemkl_dft_descriptor_set_value: -set_value -+++++++++ +``set_value`` member functions +++++++++++++++++++++++++++++++ -The ``set_value`` member function of the ``descriptor`` class sets a +The ``set_value`` member functions of any ``descriptor`` object set a configuration value corresponding to a (read-write) configuration parameter for -the DFT(s) that a ``descriptor`` object defines. This function is to be used as -many times as required for all the necessary configuration parameters to be set -prior to committing the ``descriptor`` object (by calling its member function -:ref:`onemkl_dft_descriptor_commit`). - -This function requires and expects exactly **two** arguments: it sets the -configuration value (second argument) corresponding to the configuration -parameter (first argument) ``param`` of type ``oneapi::mkl::dft::config_param``. -The type of the configuration value (second argument) to be set depends on the -value of ``param``: it can be ``oneapi::mkl::dft::config_value`` or a native -type like ``std::int64_t`` or ``float`` (more details available -:ref:`here`). +the DFT(s) that it defines. These functions are to be used as many times as +required for all the necessary configuration parameters to be set prior to +committing the object (by calling its ``commit`` +:ref:`member function`). + +All these functions require and expect exactly **two** arguments: they set the +given configuration value (second argument) for a desired configuration +parameter (first argument), represented by ``param`` of type ``config_param``. +The expected type of the associated configuration value (second argument) +depends on ``param`` and is specified in the +:ref:`section` dedicated to the ``config_param`` +type and its enumerators (unless a deprecated version is used). The expected +type of configuration value determines which of the ``set_value`` overloads is +to be used for a specific value of ``param``. + +.. rubric:: Syntax for integer-valued parameters -.. rubric:: Syntax +.. code-block:: cpp + + namespace oneapi::mkl::dft { + + template + void descriptor::set_value(config_param param, std::int64_t value); + } + +This version of ``set_value`` supports the following values of ``param``: + +- ``config_param::NUMBER_OF_TRANSFORMS``; +- ``config_param::FWD_DISTANCE``; +- ``config_param::BWD_DISTANCE``. + +.. rubric:: Syntax for real-valued parameters + +.. code-block:: cpp + + namespace oneapi::mkl::dft { + + template + void descriptor::set_value(config_param param, real_scalar_t value); + } + +This version of ``set_value`` supports the following values of ``param``: + +- ``config_param::FORWARD_SCALE``; +- ``config_param::BACKWARD_SCALE``. + + +.. rubric:: Syntax for vector-valued parameters + +.. code-block:: cpp + + namespace oneapi::mkl::dft { + + template + void descriptor::set_value(config_param param, const std::vector& value); + } + +This version of ``set_value`` supports the following values of ``param``: + +- ``config_param::FWD_STRIDES``; +- ``config_param::BWD_STRIDES``; +- ``config_param::INPUT_STRIDES`` (deprecated); +- ``config_param::OUTPUT_STRIDES`` (deprecated). + +``value`` must be a vector of :math:`\left(d+1\right)` ``std::int64_t`` elements. +More information about setting strides may be found in the page dedicated to +the :ref:`configuration of data layouts`. + +.. rubric:: Syntax for parameters associated with non-numeric values + +.. code-block:: cpp + + namespace oneapi::mkl::dft { + + template + void descriptor::set_value(config_param param, config_value value); + } + +This version of ``set_value`` supports the following values of ``param``: + +- ``config_param::COMPLEX_STORAGE``; +- ``config_param::PLACEMENT``; +- ``config_param::WORKSPACE_PLACEMENT``. + +.. rubric:: Deprecated syntax for vector-valued parameters .. code-block:: cpp namespace oneapi::mkl::dft { - template - void descriptor::set_value(oneapi::mkl::dft::config_param param, ...); + template + void descriptor::set_value(config_param param, const std::int64_t* value); + } + +This version of ``set_value`` supports the following values of ``param``: + +- ``config_param::FWD_STRIDES``; +- ``config_param::BWD_STRIDES``; +- ``config_param::INPUT_STRIDES`` (deprecated); +- ``config_param::OUTPUT_STRIDES`` (deprecated); + +and behaves as if redirecting to +``set_value(param, std::vector(value, d + 1))``. As a consequence, +``value`` must be a valid pointer to :math:`\left(d+1\right)` contiguous +``std::int64_t`` elements. + +This version is deprecated and it is recommended to use the alternative version +recommended by the compile-time deprecation warning. + +.. rubric:: Deprecated variadic syntax + +.. code-block:: cpp + + namespace oneapi::mkl::dft { + + template + void descriptor::set_value(config_param param, ...); } +This version supports all values of ``param`` corresponding to a writable +configuration parameter. The variadic argument list must contain a unique +element. When reading the latter (after default argument promotions of variadic +arguments, if applicable), oneMKL *assumes* that it is + +- an ``std::int64_t`` value if ``param`` is any of ``config_param::NUMBER_OF_TRANSFORMS``, ``config_param::FWD_DISTANCE``, or ``config_param::BWD_DISTANCE``; +- a ``double`` value if ``param`` is any of ``FORWARD_SCALE``, ``BACKWARD_SCALE``; +- a ``config_value`` value if ``param`` is any of ``config_param::COMPLEX_STORAGE``, ``config_param::PLACEMENT``, or ``config_param::WORKSPACE_PLACEMENT``; +- an ``std::int64_t*`` value (address of the first of :math:`\left(d + 1\right)` contiguous ``std::int64_t`` values) if ``param`` is any of ``config_param::FWD_STRIDES``, ``config_param::BWD_STRIDES``, ``config_param::INPUT_STRIDES``, or ``config_param::OUTPUT_STRIDES``. + +This variadic function is deprecated; it may emit runtime deprecation warnings +to inform about the recommended alternative. + .. container:: section .. rubric:: Input Parameters - param - One of the possible values of type :ref:`onemkl_dft_enum_config_param` - representing the (writable) configuration parameter to be set. + ``param`` + One of the possible values of type ``config_param`` representing the + (writable) configuration parameter to be set. + + ``value`` + The value to be set for the targeted configuration parameter. The type of + this input argument depends on ``param`` as specified above. - ... - An element of the appropriate type for the configuration value - corresponding to the targeted configuration - parameter ``param`` (appropriate type defined - :ref:`here`). + ``...`` + The value to be set for the targeted configuration parameter, passed as + a variadic argument list of **one** element. This usage is deprecated. + Note the type assumed by oneMKL when reading that value (specified above). .. container:: section .. rubric:: Throws - The ``descriptor::set_value()`` 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: + The ``set_value`` member functions shall throw the following + :ref:`exceptions` if the associated condition is + detected. An implementation may throw additional implementation-specific + exception(s) in case of error conditions not covered here: - :ref:`oneapi::mkl::invalid_argument()` - If the provided :ref:`onemkl_dft_enum_config_param` and/or configuration - value is not valid. + ``oneapi::mkl::invalid_argument()`` + - If the provided ``param`` corresponds to a read-only configuration parameter; + - If the overloaded version being used does not support ``param``; + - If the provided ``param`` and/or configuration value are/is not valid. + + ``oneapi::mkl::unimplemented()`` + If the provided ``param`` and configuration value are valid, but not + supported by the library implementation. - :ref:`oneapi::mkl::unimplemented()` - If the provided :ref:`onemkl_dft_enum_config_param` and configuration - value are valid, but not supported by the library implementation. - - **Descriptor class member table:** :ref:`onemkl_dft_descriptor_member_table` .. _onemkl_dft_descriptor_get_value: -get_value -+++++++++ +``get_value`` member functions +++++++++++++++++++++++++++++++ -The ``get_value`` member function of the ``descriptor`` class queries the -configuration value corresponding to any configuration parameter for the DFT -that a ``descriptor`` object defines. +The ``get_value`` member functions of any ``descriptor`` object query the +configuration value corresponding to a configuration parameter for the DFT that +it defines. The ``get_value`` member functions do not modify the calling object. -This function requires and expects exactly **two** arguments: it returns the +These functions require and expect exactly **two** arguments: they return the configuration value (into the element pointed by the second argument) corresponding to the queried configuration parameter (first argument) ``param`` -of type ``oneapi::mkl::dft::config_param``. The type of the second argument -depends on the value of ``param``: it is a pointer to a writable element of -type ``oneapi::mkl::dft::domain``, ``oneapi::mkl::dft::precision``, -``oneapi::mkl::dft::config_value`` or a native type like ``std::int64_t`` or -``float`` (more details available :ref:`here`). +of type ``config_param``. The second argument is a valid *pointer* to a +configuration value whose type corresponds to ``param``, as specified in the +:ref:`section` dedicated to the ``config_param`` +type and its enumerators (unless a deprecated version is used). The expected +type of configuration value determines which of the ``get_value`` overloads is +to be used for a specific value of ``param``. .. note:: - The value returned by ``get_value`` corresponds to the latest value set for - the corresponding configuration parameter being queried or the - corresponding default value if that parameter was not set or if it is not - writable, even if that value was set after the descriptor was committed. + When querying the value associated with a writable configuration parameter, + the returned value corresponds to the latest value that was set, even if it + was set after committing the descriptor. If the value was never set + explicitly, the corresponding default value is returned. -.. rubric:: Syntax +.. rubric:: Syntax for querying the kind of forward domain + +.. code-block:: cpp + + namespace oneapi::mkl::dft { + + template + void descriptor::get_value(config_param param, domain* value_ptr) const; + } + +This version of ``get_value`` supports only ``config_param::FORWARD_DOMAIN`` for +``param``. + +.. rubric:: Syntax for querying the considered floating-point format + +.. code-block:: cpp + + namespace oneapi::mkl::dft { + + template + void descriptor::get_value(config_param param, precision* value_ptr) const; + } + +This version of ``get_value`` supports only ``config_param::PRECISION`` for +``param``. + +.. rubric:: Syntax for integer-valued parameters + +.. code-block:: cpp + + namespace oneapi::mkl::dft { + + template + void descriptor::get_value(config_param param, std::int64_t* value_ptr) const; + } + +This version of ``get_value`` supports the following values of ``param``: + +- ``config_param::NUMBER_OF_TRANSFORMS``; +- ``config_param::FWD_DISTANCE``; +- ``config_param::BWD_DISTANCE``; +- ``config_param::DIMENSION``; +- ``config_param::WORKSPACE_EXTERNAL_BYTES`` (requires the calling object to be committed); +- ``config_param::LENGTHS`` (deprecated usage if :math:`d > 1`, :math:`d` contiguous ``std::int64_t`` written by oneMKL) +- ``config_param::INPUT_STRIDES`` (deprecated usage, :math:`\left(d+1\right)` contiguous ``std::int64_t`` written by oneMKL); +- ``config_param::OUTPUT_STRIDES`` (deprecated usage, :math:`\left(d+1\right)` contiguous ``std::int64_t`` written by oneMKL); +- ``config_param::FWD_STRIDES`` (deprecated usage, :math:`\left(d+1\right)` contiguous ``std::int64_t`` written by oneMKL); +- ``config_param::BWD_STRIDES`` (deprecated usage, :math:`\left(d+1\right)` contiguous ``std::int64_t`` written by oneMKL); + +Using this version for querying configuration values encapsulating more than one +``std::int64_t`` values is deprecated. A runtime deprecation warning may be +emitted to inform about the recommended alternative in such cases. + +.. rubric:: Syntax for real-valued parameters + +.. code-block:: cpp + + namespace oneapi::mkl::dft { + + template + void descriptor::get_value(config_param param, real_scalar_t* value_ptr) const; + } + +This version of ``get_value`` supports the following values of ``param``: + +- ``config_param::FORWARD_SCALE``; +- ``config_param::BACKWARD_SCALE``. + +Note that ``real_scalar_t`` is defined as ``float`` (resp. ``double``) for +single-precision (resp. double-precision) descriptors. + +.. rubric:: Syntax for vector-valued parameters + +.. code-block:: cpp + + namespace oneapi::mkl::dft { + + template + void descriptor::get_value(config_param param, std::vector* value_ptr) const; + } + +This version of ``get_value`` supports the following values of ``param``: + +- ``config_param::NUMBER_OF_TRANSFORMS`` (requires ``value_ptr->size() == 1``); +- ``config_param::FWD_DISTANCE`` (requires ``value_ptr->size() == 1``); +- ``config_param::BWD_DISTANCE`` (requires ``value_ptr->size() == 1``); +- ``config_param::DIMENSION`` (requires ``value_ptr->size() == 1``); +- ``config_param::WORKSPACE_EXTERNAL_BYTES`` (requires ``value_ptr->size() == 1``); +- ``config_param::LENGTHS`` (requires ``value_ptr->size() == d``); +- ``config_param::INPUT_STRIDES`` (requires ``value_ptr->size() == d + 1``); +- ``config_param::OUTPUT_STRIDES`` (requires ``value_ptr->size() == d + 1``); +- ``config_param::FWD_STRIDES`` (requires ``value_ptr->size() == d + 1``); +- ``config_param::BWD_STRIDES`` (requires ``value_ptr->size() == d + 1``). + +.. rubric:: Syntax for other non-numeric parameters + +.. code-block:: cpp + + namespace oneapi::mkl::dft { + + template + void descriptor::get_value(config_param param, config_value* value_ptr) const; + } + +This version of ``get_value`` supports the following values of ``param``: + +- ``config_param::COMMIT_STATUS``; +- ``config_param::COMPLEX_STORAGE``; +- ``config_param::PLACEMENT``; +- ``config_param::WORKSPACE_PLACEMENT``. + +.. rubric:: Deprecated variadic syntax .. code-block:: cpp namespace oneapi::mkl::dft { - template - void descriptor::get_value(oneapi::mkl::dft::config_param param, ...); + template + void descriptor::get_value(config_param param, ...) const; } +This version supports all values of ``param``. The variadic argument list must +contain a unique element. When reading the latter (after default argument +promotions of variadic arguments, if applicable), oneMKL assumes that it is of +type + +- ``domain*`` if ``param`` is ``config_param::FORWARD_DOMAIN``; +- ``precision*`` if ``param`` is ``config_param::PRECISION``; +- ``std::int64_t*`` if ``param`` is any of ``config_param::NUMBER_OF_TRANSFORMS``, ``config_param::FWD_DISTANCE``, ``config_param::BWD_DISTANCE``, ``config_param::DIMENSION``, ``config_param::WORKSPACE_EXTERNAL_BYTES``, ``config_param::LENGTHS``, ``config_param::INPUT_STRIDES``, ``config_param::OUTPUT_STRIDES``, ``config_param::FWD_STRIDES``, or ``config_param::BWD_STRIDES``; +- ``float*`` (resp. ``double*``) if ``param`` is any of ``config_param::FORWARD_SCALE`` or ``config_param::BACKWARD_SCALE``, for single-precision (resp. double-precision) descriptors; +- ``config_value*`` if ``param`` is any of ``config::param::COMMIT_STATUS``, ``config::param::COMPLEX_STORAGE``, ``config::param::PLACEMENT``, or ``config::param::WORKSPACE_PLACEMENT``. + +This variadic function is deprecated and behaves as if redirecting to the +overloaded non-variadic overloaded alternative (possibly deprecated itself) that +is consistent with that assumed type. It may emit runtime deprecation warnings +to inform about the recommended alternative. + .. container:: section .. rubric:: Input Parameters - param - One of the possible values of type :ref:`onemkl_dft_enum_config_param` - representing the configuration parameter being queried. + ``param`` + One of the possible values of type ``config_param`` representing the + configuration parameter being queried. - ... - A pointer to a writable element of the appropriate type for the - configuration value corresponding to the queried configuration - parameter ``param`` (appropriate type of pointed element defined - :ref:`here`). +.. container:: section + + .. rubric:: Output Parameters + + ``value_ptr`` + A valid *pointer* to a configuration value (or configuration values) in + which oneMKL is allowed to write (return) the queried value(s). The type + of this input argument depends on ``param`` as specified above. + + ``...`` + A valid *pointer* to a configuration value (or configuration values), + passed as a variadic argument list of **one** element. This usage is + deprecated. Note the type assumed by oneMKL when accessing that pointer + (specified above) .. container:: section .. rubric:: Throws - The ``descriptor::get_value()`` 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: + The ``get_value`` member functions shall throw the following + :ref:`exceptions` if the associated condition is + detected. An implementation may throw additional implementation-specific + exception(s) in case of error conditions not covered here: - :ref:`oneapi::mkl::invalid_argument()` - If the requested :ref:`onemkl_dft_enum_config_param` is not valid. + ``oneapi::mkl::invalid_argument()`` + - If the overloaded version being used does not support ``param``; + - If ``value_ptr`` is ``nullptr``; + - If ``value_ptr->size()`` is not as expected when querying a vector-valued parameter. + + ``oneapi::mkl::uninitialized`` + If ``param`` is ``config_param::WORKSPACE_EXTERNAL_BYTES`` and the + calling object is not committed. + + ``oneapi::mkl::unimplemented()`` + If the queried ``param`` is valid, but not supported by the library + implementation. **Descriptor class member table:** :ref:`onemkl_dft_descriptor_member_table` .. _onemkl_dft_descriptor_set_workspace: -set_workspace -+++++++++++++ +``set_workspace`` member function ++++++++++++++++++++++++++++++++++ -Sets the workspace for when ``config_param::WORKSPACE_PLACEMENT`` is set to ``config_value::WORKSPACE_EXTERNAL``. +The ``set_workspace`` member function of any ``descriptor`` object sets the +workspace (possible additional memory required by the object for computation +purposes) to use when computing DFTs. -.. rubric:: Description +This function may only be called after the ``descriptor`` object has been +committed. The size of the provided workspace must be equal to or larger than +the required workspace size, *i.e.*, the configuration value associated with +``config_param::WORKSPACE_EXTERNAL_BYTES`` (queryable via the ``get_value`` +member function for integer-valued parameters). -This function sets the workspace to use when computing DFTs for when an -external workspace is set. -This function may only be called after the descriptor has been committed. -The size of the provided workspace must be equal to or larger than the required -workspace size obtained by calling ``descriptor::get_value(config_param::WORKSPACE_EXTERNAL_BYTES, &workspaceBytes)``. - -A descriptor where ``config_value::WORKSPACE_EXTERNAL`` is specified for -``config_param::WORKSPACE_PLACEMENT`` is not a valid descriptor for compute -calls until this function has been successfully called. +A ``descriptor`` object where ``config_value::WORKSPACE_EXTERNAL`` is specified +for ``config_param::WORKSPACE_PLACEMENT`` is not a valid object for compute +calls until its workspace has been successfully set using this member function. The type of workspace must match the compute calls for which it is used. That is, if the workspace is provided as a ``sycl::buffer``, the compute @@ -460,8 +738,8 @@ be used in compute calls. However, the aforementioned restrictions will still ap namespace oneapi::mkl::dft { - template - void descriptor::set_workspace(sycl::buffer &workspaceBuf); + template + void descriptor::set_workspace(sycl::buffer &workspaceBuf); } .. rubric:: Syntax (USM workspace) @@ -470,8 +748,8 @@ be used in compute calls. However, the aforementioned restrictions will still ap namespace oneapi::mkl::dft { - template - void descriptor::set_workspace(scalar_type* workspaceUSM); + template + void descriptor::set_workspace(real_scalar_t* workspaceUSM); } @@ -479,22 +757,35 @@ be used in compute calls. However, the aforementioned restrictions will still ap .. rubric:: Input Parameters - workspaceBuf - A workspace buffer where ``scalar_type`` is the floating-point type according to ``prec``. This buffer must be sufficiently large or an exception will be thrown. A sub-buffer cannot be used. + ``workspaceBuf`` + A workspace buffer where ``real_scalar_t`` is the floating-point type + according to ``prec``. This buffer must be sufficiently large or an + exception will be thrown. A sub-buffer cannot be used. - workspaceUSM - A workspace USM allocation where ``scalar_type`` is the floating-point type according to ``prec``. This allocation must be accessible on the device on which the descriptor is committed. It is assumed that this USM allocation is sufficiently large. The pointer is expected to be aligned to ``scalar_type``. + ``workspaceUSM`` + A workspace USM allocation where ``real_scalar_t`` is the floating-point + type according to ``prec``. This allocation must be accessible on the + device on which the descriptor is committed. It is assumed that this USM + allocation is sufficiently large. The pointer is expected to be aligned + to ``real_scalar_t``. .. container:: section .. rubric:: Throws - The ``descriptor::set_workspace()`` 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: + The ``set_workspace`` member function shall throw the following + :ref:`exceptions` if the associated condition is + detected. An implementation may throw additional implementation-specific + exception(s) in case of error conditions not covered here: - :ref:`oneapi::mkl::invalid_argument()` - If the provided buffer ``workspaceBuf`` is not sufficiently large or is a sub-buffer, or if the provided USM allocation ``workspaceUSM`` is ``nullptr`` when an external workspace of size greater than zero is required. - - :ref:`oneapi::mkl::uninitialized()` + ``oneapi::mkl::invalid_argument()`` + If the provided buffer ``workspaceBuf`` is not sufficiently large or is a + sub-buffer, or if the provided USM allocation ``workspaceUSM`` is + ``nullptr`` when an external workspace of size greater than zero is + required, or if the provided USM allocation ``workspaceUSM`` is not + accessible by the device. + + ``oneapi::mkl::uninitialized()`` If ``set_workspace`` is called before the descriptor is committed. @@ -502,24 +793,24 @@ be used in compute calls. However, the aforementioned restrictions will still ap .. _onemkl_dft_descriptor_commit: -commit -++++++ +``commit`` member function +++++++++++++++++++++++++++ The ``commit`` member function commits a ``descriptor`` object to the DFT calculations it defines consistently with its configuration settings, by completing all the initialization work (*e.g.*, algorithm selection, algorithm tuning, choice of factorization, memory allocations, calculation of twiddle factors, etc.) required by the chosen implementation for the desired DFT(s) on -the targeted device. Objects of the ``descriptor`` class **must** be committed -prior to using them in any call to :ref:`onemkl_dft_compute_forward` or -:ref:`onemkl_dft_compute_backward` (which trigger actual DFT calculations). +the targeted device. Objects of any ``descriptor`` class **must** be committed +prior to using them in any call to ``compute_forward`` or ``compute_backward`` +(which trigger actual DFT calculations). As specified :ref:`above`, all required configuration parameters must be set before this function is called. Any change in configuration operated on a ``descriptor`` object via a call to its -:ref:`onemkl_dft_descriptor_set_value` member function *after* it was committed -results in an undefined state not suitable for computation until this ``commit`` member -function is called again. +``set_value`` member function *after* it was committed results in an undefined +state not suitable for computation until this ``commit`` member function is +called again. .. rubric:: Syntax @@ -527,7 +818,7 @@ function is called again. namespace oneapi::mkl::dft { - template + template void descriptor::commit(sycl::queue& queue); } @@ -535,7 +826,7 @@ function is called again. .. rubric:: Input Parameters - queue + ``queue`` Valid ``sycl::queue`` object to which the operations relevant to the desired DFT(s) are to be enqueued. @@ -543,20 +834,21 @@ function is called again. .. rubric:: Throws - The ``descriptor::commit()`` 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 (if the ``descriptor`` object's configuration was found to be - inconsistent, for instance): + The ``commit`` member function shall throw the following + :ref:`exceptions` if the associated condition is + detected. An implementation may throw additional implementation-specific + exception(s) in case of error conditions not covered here (if the + ``descriptor`` object's configuration was found to be inconsistent, for + instance): - :ref:`oneapi::mkl::invalid_argument()` - If the queue is found to be invalid in any way. + ``oneapi::mkl::invalid_argument()`` + If ``queue`` is found to be invalid in any way. - :ref:`oneapi::mkl::host_bad_alloc()` + ``oneapi::mkl::host_bad_alloc()`` If any host side only memory allocations fail, for instance due to lack of memory. - :ref:`oneapi::mkl::device_bad_alloc()` + ``oneapi::mkl::device_bad_alloc()`` If any device or shared memory allocation fail. **Descriptor class member table:** :ref:`onemkl_dft_descriptor_member_table` diff --git a/source/elements/oneMKL/source/domains/dft/dft.rst b/source/elements/oneMKL/source/domains/dft/dft.rst index aafbe1e248..7268c7cf76 100644 --- a/source/elements/oneMKL/source/domains/dft/dft.rst +++ b/source/elements/oneMKL/source/domains/dft/dft.rst @@ -15,30 +15,30 @@ oneMKL provides a DPC++ interface to :math:`d`-dimensional :math:`\left(d \in Definitions +++++++++++ +Let :math:`w` be a set of :math:`M` finite :math:`d`-dimensional discrete +sequences :math:`w^{m}` of length(s) :math:`n_1 \times n_2 \times \dots \times n_d` +(:math:`d \in \mathbb{Z}_{>0}`, :math:`M \in \mathbb{Z}_{>0}`, +:math:`n_{\ell} \in \mathbb{Z}_{>0}\ \forall \ell \in \lbrace 1, 2, \ldots, d \rbrace`, +and :math:`m \in \lbrace 0, 1, \ldots, M-1\rbrace`). Let :math:`w^{m}_{k_1, k_2, \ldots, k_d}` be the entry of multi-index -:math:`\left(k_1, k_2, \ldots, k_d\right) \in \mathbb{Z}^d` in the -:math:`m`-th sequence of a set :math:`w` of :math:`M` :math:`d`-dimensional -periodic discrete sequences of period(s) (or "length(s)") -:math:`n_1 \times n_2 \times \dots \times n_d` -(:math:`M \in \mathbb{Z}_{>0}`, :math:`m \in \lbrace 0, 1, \ldots, M-1\rbrace` -and -:math:`n_{\ell} \in \mathbb{Z}_{>0}, \forall \ell \in \lbrace 1, \ldots, d \rbrace`). +:math:`\left(k_1, k_2, \ldots, k_d\right)` in :math:`w^{m}` wherein integer +indices :math:`k_{\ell}` are such that +:math:`0 \leq k_{\ell} < n_{\ell},\ \forall \ell \in \lbrace 1, 2, \ldots, d \rbrace`. For every :math:`m \in \lbrace 0, 1, \ldots, M - 1 \rbrace`, the DFT of sequence -:math:`w^{m}` is the :math:`d`-dimensional -:math:`n_1 \times n_2 \times \dots \times n_d` periodic discrete sequence -:math:`z^{m}` whose entries are defined as +:math:`w^{m}` is the :math:`d`-dimensional discrete sequence :math:`z^{m}` of +length(s) :math:`n_1 \times n_2 \times \dots \times n_d` whose entries are defined as .. _onemkl_dft_formula: .. math:: - z^{m}_{k_1, k_2,\ldots, k_d} = \sigma \displaystyle\sum_{j_d=0}^{n_d-1}\dots\displaystyle\sum_{j_2=0}^{n_2-1}\displaystyle\sum_{j_1=0}^{n_1-1} w^{m}_{j_1, j_2,\dots,j_d} \exp \left[ \delta 2\pi \imath \left( \sum_{\ell=1}^{d} \frac{j_{\ell}k_{\ell}}{n_{\ell}} \right) \right] \ \forall \left(k_1, \ldots, k_d\right) \in \mathbb{Z}^{d} + z^{m}_{k_1, k_2,\ldots, k_d} = \sigma_{\delta} \displaystyle\sum_{j_d=0}^{n_d-1}\dots\displaystyle\sum_{j_2=0}^{n_2-1}\displaystyle\sum_{j_1=0}^{n_1-1} w^{m}_{j_1, j_2,\dots,j_d} \exp \left[ \delta 2\pi \imath \left( \sum_{\ell=1}^{d} \frac{j_{\ell}k_{\ell}}{n_{\ell}} \right) \right], :label: eq_dft_definition -where :math:`\imath^2 = -1` and :math:`\sigma` is a scale factor. -In :eq:`eq_dft_definition`, :math:`\delta` determines one of the two -"directions" of the DFT: :math:`\delta=-1` defines the "forward DFT" while -:math:`\delta=+1` defines the "backward DFT". +where :math:`\imath^2 = -1`. In :eq:`eq_dft_definition`, :math:`\delta` +determines one of the two "directions" of the DFT: :math:`\delta=-1` defines the +"forward DFT" while :math:`\delta=+1` defines the "backward DFT". +:math:`\sigma_{\delta}` is a (real) scaling factor associated with either operation. The domain of input (resp. output) discrete sequences for a forward (resp. backward) DFT is referred to as "forward domain". Conversely, the domain of @@ -46,55 +46,49 @@ output (resp. input) discrete sequences for forward (resp. backward) DFT is referred to as "backward domain". oneMKL supports single-precision (fp32) and double-precision (fp64) -floating-point arithmetic for the calculation of DFTs, using two types of +floating-point arithmetic for the calculation of DFTs, using two kinds of forward domains: -- the set of complex :math:`d`-dimensional periodic sequences, referred to as +- the set of complex :math:`d`-dimensional discrete sequences, referred to as "complex forward domain"; -- the set of real :math:`d`-dimensional periodic sequences, referred to as +- the set of real :math:`d`-dimensional discrete sequences, referred to as "real forward domain". Similarly, we refer to DFTs of complex (resp. real) forward domain as "complex -DFTs" (resp. "real DFTs"). Regardless of the type of forward domain, the +DFTs" (resp. "real DFTs"). Regardless of the kind of forward domain, the backward domain's data sequences are always complex. The calculation of the same DFT for several, *i.e.*, :math:`M > 1`, data sets of -the same type of forward domain, using the same precision is referred to as a +the same kind of forward domain, using the same precision is referred to as a "batched DFT". -.. _onemkl_dft_finite_range_of_indices: +.. _onemkl_dft_elementary_range_of_indices: -Finite range of indices -+++++++++++++++++++++++ +Elementary range of indices ++++++++++++++++++++++++++++ -In general, given the periodicity of the discrete data considered in any DFT, -ranges of indices :math:`\left(k_1, \ldots, k_d\right) \in \mathbb{Z}^{d}` such -that :math:`0\leq k_{\ell} < n_{\ell}, \forall \ell \in \lbrace 1, \ldots, d -\rbrace` suffice to determine any relevant :math:`d`-dimensional sequence +In general, all entries of multi-indices :math:`\left(k_1, \ldots, k_d\right)` +such that :math:`0\leq k_{\ell} < n_{\ell}, \forall \ell \in \lbrace 1, \ldots, d \rbrace` +unambiguously determine any relevant :math:`d`-dimensional sequence unambiguously (for any valid :math:`m`). In case of real DFTs, the data sequences in backward domain can be fully determined from a smaller range of indices. Indeed, if all entries of :math:`w` are real in :eq:`eq_dft_definition`, then the entries of :math:`z` are complex and, for any valid :math:`m`, -:math:`\left(z^{m}_{k_1, k_2, \dots, k_d}\right)^{*} = z^{m}_{n_1 - k_1, n_2 - k_2, \dots, n_d - k_d}` -:math:`\forall \left(k_1, k_2, \ldots, k_d\right) \in \mathbb{Z}^{d}` where -:math:`\lambda^{*}` represents the conjugate of complex number :math:`\lambda`. -This conjugate symmetry relation makes roughly half the data redundant in -backward domain: in case of real DFTs, the data sequences in backward domain can -be fully determined even if one of the :math:`d` indices :math:`k_{\ell}` is -limited to the range +:math:`\left(z^{m}_{k_1, k_2, \dots, k_d}\right)^{*} = z^{m}_{j_{1}, j_{2}, \dots, j_{d}}` where +:math:`j_{\ell} = \left(n_{\ell} - k_{\ell}\right) \pmod {n_{\ell}}, \ \forall \ell \in \lbrace 1, \ldots, d \rbrace` +and :math:`\lambda^{*}` represents the conjugate of complex number +:math:`\lambda`. This conjugate symmetry relation makes roughly half the data +redundant in backward domain: in case of real DFTs, the data sequences in +backward domain can be fully determined even if one of the :math:`d` indices +:math:`k_{\ell}` is limited to the range :math:`0\leq k_{\ell} \leq \lfloor \frac{n_{\ell}}{2}\rfloor`. In oneMKL, the -index :math:`k_d`, *i.e.*, the last dimension's index, is restricted as such for -capturing an elementary set of non-redundant entries of data sequences belonging +index :math:`k_d`, *i.e.*, the last dimension's index, is restricted as such to +capture an elementary set of non-redundant entries for data sequences belonging to the backward domain of real DFTs. -.. _onemkl_dft_elementary_range_of_indices: - -Elementary range of indices -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - In other words, oneMKL expects and produces a set of :math:`M` -:math:`d`-dimensional *finite* data sequences +:math:`d`-dimensional data sequences :math:`\left(\cdot \right)^{m}_{k_1, k_2,\ldots, k_d}` with integer indices :math:`m` and :math:`k_{\ell}\ \left(\ell \in \lbrace 1, \ldots, d \rbrace\right)` in the @@ -137,45 +131,48 @@ DFTs. Specifically, for any of the :math:`M` sequences, Recommended usage +++++++++++++++++ -The desired (batched) DFT to be computed is entirely defined by an object -``desc`` of the :ref:`descriptor` class. The desired type -of forward domain and precision are determined at ``desc``'s construction time -by the specialization values chosen for the self-explanatory template parameters -``prec`` (of type :ref:`onemkl_dft_enum_precision`) and ``dom`` (of type -:ref:`onemkl_dft_enum_domain`), respectively. The transform size -:math:`n_1 \times n_2 \times \dots \times n_d` is also set at construction time -as a required argument to the class constructor. Other configuration details for -the (batched) DFT under consideration may be specified by invoking the -:ref:`onemkl_dft_descriptor_set_value` member function of ``desc`` for every -relevant configuration setting (*e.g.*, the number :math:`M` of sequences to -consider in case of a batched DFT). Once configured as desired, the -:ref:`onemkl_dft_descriptor_commit` member function of ``desc``, requiring a -``sycl::queue`` object ``Q``, may be invoked. The successful completion of the -latter makes ``desc`` committed to the desired (batched) DFT *as configured*, for -the particular device and context encapsulated by ``Q``. The -:ref:`onemkl_dft_compute_forward` (resp. :ref:`onemkl_dft_compute_backward`) -function may then be called and provided with ``desc`` to enqueue operations -relevant to the desired forward (resp. backward) DFT calculations with -user-provided, device-accessible data. +The desired DFT to be computed is entirely defined by an object ``desc`` of a +specialization of the ``oneapi::mkl::dft::descriptor`` +:ref:`class template`. +The desired floating-point format and kind of forward domain are determined by +``desc``'s particular class, *i.e.*, by the specialization values of the +:ref:`template parameters` ``prec`` +and ``dom`` of the ``descriptor`` class template, respectively. Once ``desc`` is +created, the length(s) :math:`\lbrace n_1, n_2, \ldots, n_d\rbrace` (and the +dimension :math:`d`) cannot be changed, as they are read-only parameters. Other +configuration details for the DFT under consideration may be specified by +invoking the appropriate +:ref:`configuration-setting member function(s)` +of ``desc`` for every relevant configuration parameter (*e.g.*, the number +:math:`M` of sequences to consider in case of a batched DFT). Once configured +as desired, ``desc`` must be initialized for computation by using its +:ref:`committing member function`, which requires +a ``sycl::queue`` object. The successful completion of that operation makes +``desc`` ready to compute the desired DFT *as configured*, for the particular +device and context encapsulated by the latter. ``desc`` may then be used with +user-provided, device-accessible data, in a +``oneapi::mkl::dft::compute_forward`` (resp. +``oneapi::mkl::dft::compute_backward``) function to enqueue operations relevant +to the desired forward (resp. backward) DFT calculations. .. note:: - Objects of the :ref:`descriptor` class + Objects of any ``oneapi::mkl::dft::descriptor`` class - must be successfully committed prior to providing them to any compute function; - - must be re-committed to account for any change in configuration after - it was already successfully committed; + - must be re-committed to account for any change in configuration operated + after they were already successfully committed; - deliver best performance for DFT calculations when created, configured and committed outside applications' hotpath(s) that use them multiple times for - identically-configured (batched) DFTs. :ref:`onemkl_dft_compute_forward` - and/or :ref:`onemkl_dft_compute_backward` should be the only oneMKL DFT-related + identically-configured DFTs. ``oneapi::mkl::dft::compute_forward`` and/or + ``oneapi::mkl::dft::compute_backward`` should be the only oneMKL DFT-related routines invoked in programs' hotpaths. Summary table ~~~~~~~~~~~~~ -The table below summarizes the object and functions relevant to computing DFTs -(all defined in the ``oneapi::mkl::dft`` namespace). +The table below summarizes the identifiers of the ``oneapi::mkl::dft`` namespace +relevant to computing DFTs. .. _onemkl_dft_summary_table: .. container:: @@ -189,34 +186,47 @@ The table below summarizes the object and functions relevant to computing DFTs :header-rows: 1 :widths: 33 64 - * - Routines and Objects - - Description - * - :ref:`descriptor` - - A class whose instances define a specific (batched) DFT(s) to - be calculated. - * - :ref:`descriptor::set_value` - - A member function of the - :ref:`descriptor` class to set (writable) - :ref:`configuration parameters` - for an instance of that class. - * - :ref:`descriptor::get_value` - - A member function of the - :ref:`descriptor` class to query - :ref:`configuration parameters` - from any instance of that class. - * - :ref:`descriptor::commit` - - A member function of the - :ref:`descriptor` class to commit an - instance of that class to the (batched) DFT calculations it - defines, on a given queue. - * - :ref:`onemkl_dft_compute_forward` - - A function requiring a successfully-committed object of the - :ref:`descriptor` class to compute a - forward (batched) DFT, as defined by that object. - * - :ref:`onemkl_dft_compute_backward` - - A function requiring a successfully-committed object of the - :ref:`descriptor` class to compute a - backward (batched) DFT, as defined by that object. + * - Identifier in ``oneapi::mkl::dft`` + - Description + * - ``descriptor`` + - A template for classes whose instances define a specific DFT to + be calculated and its configuration. Template + parameters are omitted in this table for conciseness (more + details are available in the page dedicated to + :ref:`the descriptor class template`). + * - ``domain``, ``precision``, ``config_param`` and ``config_value`` + - :ref:`Scoped enumerations` pertaining to the + definition of any configuration parameter or its associated + value, for any instance of a ``descriptor`` class. + * - ``descriptor::set_value`` + - Member functions to + :ref:`set (writable) configuration parameters` + for any instance of a ``descriptor`` class. + * - ``descriptor::get_value`` + - Member functions to + :ref:`query configuration parameters` + from any instance of a ``descriptor`` class. + * - ``descriptor::commit`` + - A member function to + :ref:`commit` any instance + of a ``descriptor`` class to the DFT calculations it defines, + on a given queue. + * - ``descriptor::set_workspace`` + - A member function to equip any instance of a ``descriptor`` + class with an + :ref:`externally-allocated workspace`. + * - ``compute_forward`` + - Function templates for computing a forward DFT, as defined by + a (successfully-committed) instance of a ``descriptor`` class + (required argument). Template parameters are omitted in this + table for conciseness (more details are available in the + :ref:`dedicated page`). + * - ``compute_backward`` + - Function templates for computing a backward DFT, as defined by + a (successfully-committed) instance of a ``descriptor`` class + (required argument). Template parameters are omitted in this + table for conciseness (more details are available in the + :ref:`dedicated page`). **Parent topic:** :ref:`onemkl_domains` diff --git a/source/elements/oneMKL/source/domains/dft/enums_and_config_params.rst b/source/elements/oneMKL/source/domains/dft/enums_and_config_params.rst index 9e69d80eb3..6c86a0e9b8 100644 --- a/source/elements/oneMKL/source/domains/dft/enums_and_config_params.rst +++ b/source/elements/oneMKL/source/domains/dft/enums_and_config_params.rst @@ -8,9 +8,9 @@ DFT-related scoped enumeration types ------------------------------------ The following scoped enumeration types, defined in the ``oneapi::mkl::dft`` -namespace, are used for constructing and configuring objects of the -:ref:`descriptor` class consistently with the DFT(s) they -are meant to define. +namespace, are used for constructing and configuring ``descriptor`` objects +consistently with the DFT(s) they are meant to define. The usage of prepended +namespace specifiers ``oneapi::mkl::dft`` is omitted below for conciseness. .. list-table:: :header-rows: 1 @@ -18,229 +18,222 @@ are meant to define. * - Scoped enumeration type - Description - * - :ref:`onemkl_dft_enum_precision` - - Represents the precision of the floating-point data format and of - the floating-point arithmetic to be used for the desired DFT - calculations. A template parameter ``prec`` of this type is used for - the :ref:`descriptor` class. - * - :ref:`onemkl_dft_enum_domain` - - Represents the type of forward domain for the desired DFT(s). A - template parameter ``dom`` of this type is used for the - :ref:`descriptor` class. - * - :ref:`onemkl_dft_enum_config_param` - - Represents configuration parameters for objects of the - :ref:`descriptor` class. The configuration - values associated with the configuration parameters - can be retrieved (resp. set, for writable parameters) via the object's - :ref:`onemkl_dft_descriptor_get_value` (resp. - :ref:`onemkl_dft_descriptor_set_value`) member function. - * - :ref:`onemkl_dft_enum_config_value` - - Represents the possible configuration values for some of the - :ref:`configuration parameters` that - may take only a few determined, non-numeric values. + * - ``precision`` + - Type for the floating-point format to be used in the desired DFT + calculations (for arithmetic operations and data representation). A + template parameter ``prec`` of this type is used for the + ``descriptor`` :ref:`class template`. + * - ``domain`` + - Type for the kind of forward domain for the desired DFT calculations. + A template parameter ``dom`` of this type is used for the + ``descriptor`` :ref:`class template`. + * - ``config_param`` + - Type for configuration parameters of ``descriptor`` objects. + * - ``config_value`` + - Type for non-numeric configuration values corresponding to some of + the :ref:`configuration parameters`. .. _onemkl_dft_enum_precision: -precision -+++++++++ +``precision`` ++++++++++++++ -This scoped enumeration type represents the precision of the floating-point -format to be used for the desired DFT(s). The same precision is to be used for -the user-provided data, the computation being carried out by oneMKL and the -results delivered by oneMKL. +Values in this scoped enumeration type represent the floating-point format to be +used for the desired DFT(s). The same format is to be used for the user-provided +data, the computation being carried out by oneMKL and the delivered results. .. container:: section .. rubric:: Syntax .. code:: cpp - - enum class precision { - SINGLE, - DOUBLE - }; + + namespace oneapi::mkl::dft { + enum class precision { + SINGLE, + DOUBLE + }; + } .. list-table:: :header-rows: 1 :widths: 24 73 - * - Value + * - ``precision`` enumerator - Description - * - SINGLE + * - ``SINGLE`` - Single-precision floating-point format (FP32) is used for data representation and arithmetic operations. - * - DOUBLE + * - ``DOUBLE`` - Double-precision floating-point format (FP64) is used for data representation and arithmetic operations. .. _onemkl_dft_enum_domain: -domain -++++++ +``domain`` +++++++++++ -This scoped enumeration type represents the type of forward domain for the -desired DFTs (as explained in the :ref:`introduction`, -the backward domain type is always complex). +Values in this scoped enumeration type represent the kind of forward domain for +the desired DFT(s). As explained in the :ref:`introduction`, +the backward domain type is always complex. .. container:: section .. rubric:: Syntax .. code:: cpp - - enum class domain { - REAL, - COMPLEX - }; + + namespace oneapi::mkl::dft { + enum class domain { + REAL, + COMPLEX + }; + } .. list-table:: :header-rows: 1 :widths: 24 73 - * - Value + * - ``domain`` enumerator - Description - * - REAL - - The forward domain is the set of real :math:`d`-dimensional periodic - sequences. - * - COMPLEX - - The forward domain is the set of complex :math:`d`-dimensional - periodic sequences. + * - ``REAL`` + - The forward domain is the set of real :math:`d`-dimensional sequences. + * - ``COMPLEX`` + - The forward domain is the set of complex :math:`d`-dimensional sequences. .. _onemkl_dft_enum_config_param: -config_param -++++++++++++ +``config_param`` +++++++++++++++++ -This scoped enumeration type represents configuration parameters for objects of -the :ref:`descriptor` class. +Values in this scoped enumeration type represent configuration parameters for +``descriptor`` objects. .. container:: section .. code:: cpp - - enum class config_param { - // read-only parameters: - FORWARD_DOMAIN, - DIMENSION, - LENGTHS, - PRECISION, - COMMIT_STATUS, - // writable parameters: - FORWARD_SCALE, - BACKWARD_SCALE, - - NUMBER_OF_TRANSFORMS, - - COMPLEX_STORAGE, - - PLACEMENT, - - FWD_STRIDES, - BWD_STRIDES, - INPUT_STRIDES, // deprecated - OUTPUT_STRIDES, // deprecated - - FWD_DISTANCE, - BWD_DISTANCE, - - WORKSPACE_PLACEMENT, - WORKSPACE_EXTERNAL_BYTES - }; + + namespace oneapi::mkl::dft { + enum class config_param { + // read-only parameters: + FORWARD_DOMAIN, + DIMENSION, + LENGTHS, + PRECISION, + COMMIT_STATUS, + WORKSPACE_EXTERNAL_BYTES, + // writable parameters: + FORWARD_SCALE, + BACKWARD_SCALE, + + NUMBER_OF_TRANSFORMS, + + COMPLEX_STORAGE, + + PLACEMENT, + + FWD_STRIDES, + BWD_STRIDES, + INPUT_STRIDES, // deprecated + OUTPUT_STRIDES, // deprecated + + FWD_DISTANCE, + BWD_DISTANCE, + + WORKSPACE_PLACEMENT + }; + } Configuration parameters represented by ``config_param::FORWARD_DOMAIN`` and ``config_param::PRECISION`` are associated with configuration values of type - :ref:`domain` and - :ref:`precision` respectively. Other - configuration parameters are associated with configuration values of type - :ref:`onemkl_dft_enum_config_value` or of a native type like - ``std::int64_t``, ``std::vector``, ``float`` or ``double``. - This is further specified in the following table. + ``domain`` and ``precision`` respectively. Other configuration parameters are + associated with configuration values of type ``config_value`` or of a native + type like ``std::int64_t``, ``std::vector``, ``float`` or + ``double``. This is further specified in the following table. .. list-table:: :header-rows: 1 :widths: 10 50 40 - * - | Value of ``config_param`` - | - - | Represented configuration parameter(s) - | + * - ``config_param`` enumerator + - Represented configuration parameter - | Type of associated configuration value | [default value] - * - FORWARD_DOMAIN - - Type of forward domain, set at construction time as the - specialization value of :ref:`onemkl_dft_enum_domain` template - parameter ``dom``. This parameter is read-only. - - | :ref:`onemkl_dft_enum_domain` - | [``dom``] - * - DIMENSION - - Value of the dimension :math:`d` of the desired DFTs, set at - construction time. This parameter is read-only. + * - ``FORWARD_DOMAIN`` + - Kind of forward domain for the DFT. This parameter is read-only. + - | ``domain`` + | [specialization value used for template parameter ``dom`` of the + ``descriptor`` :ref:`class template`] + * - ``DIMENSION`` + - Dimension :math:`d` of the DFT. This parameter is read-only. - | ``std::int64_t`` | [:math:`d`] - * - LENGTHS - - Values :math:`\lbrace n_1, \ldots, n_d\rbrace` of the periods (or - "lengths") of the desired DFT, set at construction time. This - parameter is read-only. + * - ``LENGTHS`` + - Lengths :math:`\lbrace n_1, \ldots, n_d\rbrace` of the DFT. This + parameter is read-only and can only be set via the + :ref:`parameterized constructors`. - | ``std::vector`` of size :math:`d` or, if :math:`d = 1`, ``std::int64_t`` | [``std::vector({n_1,...,n_d})``] - * - PRECISION - - Floating-point precision to be considered by and used for the DFT - calculation(s), set at construction time as the specialization value - of :ref:`onemkl_dft_enum_precision` template parameter ``prec``. - This parameter is read-only. - - | :ref:`onemkl_dft_enum_precision` - | [``prec``] - * - COMMIT_STATUS - - Status flag indicating whether the object is ready for computations - after a successful call to :ref:`onemkl_dft_descriptor_commit`. This + * - ``PRECISION`` + - Floating-point format to use for the DFT data and computation. This parameter is read-only. - - | :ref:`onemkl_dft_enum_config_value` (possible values are self-explanatory ``config_value::COMMITTED`` or ``config_value::UNCOMMITTED``). + - | ``precision`` + | [specialization value used for template parameter ``prec`` of the + ``descriptor`` :ref:`class template`] + * - ``COMMIT_STATUS`` + - Status flag indicating whether the object is ready for computations + after a successful call to its ``commit`` + :ref:`member function`. This parameter + is read-only. + - | ``config_value`` (possible values are ``config_value::COMMITTED`` or ``config_value::UNCOMMITTED``). | [``config_value::UNCOMMITTED``] - * - FORWARD_SCALE - - Value of :math:`\sigma` for the forward DFT. + * - ``FORWARD_SCALE`` + - :math:`\sigma_{\delta}` for the forward DFT (:math:`\delta = -1`). - | ``float`` (resp. ``double``) for single-precision (resp. double-precision) descriptors - | [1.0] - * - BACKWARD_SCALE - - Value of :math:`\sigma` for the backward DFT. + | [:math:`1.0`] + * - ``BACKWARD_SCALE`` + - :math:`\sigma_{\delta}` for the backward DFT (:math:`\delta = +1`). - | ``float`` (resp. ``double``) for single-precision (resp. double-precision) descriptors - | [1.0] - * - :ref:`NUMBER_OF_TRANSFORMS` - - Value of :math:`M`. This is relevant (and *must* be set) for + | [:math:`1.0`] + * - ``NUMBER_OF_TRANSFORMS`` + - Batch size :math:`M`. This is relevant (and *must* be set) for batched DFT(s), *i.e.*, if :math:`M > 1`. - | ``std::int64_t`` - | [1] - * - :ref:`COMPLEX_STORAGE` - - Data storage type used (relevant for complex descriptors only). - - | :ref:`onemkl_dft_enum_config_value` (possible values are ``config_value::COMPLEX_COMPLEX`` or ``config_value::REAL_REAL``) + | [:math:`1`] + * - ``COMPLEX_STORAGE`` + - :ref:`Data storage` type used (relevant + for complex descriptors only). + - | ``config_value`` (possible values are ``config_value::COMPLEX_COMPLEX`` or ``config_value::REAL_REAL``) | [``config_value::COMPLEX_COMPLEX``] - * - PLACEMENT + * - ``PLACEMENT`` - | Parameter specifying whether the DFT calculations should be done in-place (results overwriting the input data) or out-of-place (input and output in separate data containers having no common elements). | Note: even for out-of-place configurations, some implementations may not preserve the original input data. - - | :ref:`onemkl_dft_enum_config_value` (possible values are self-explanatory ``config_value::INPLACE`` or ``config_value::NOT_INPLACE``) + - | ``config_value`` (possible values are ``config_value::INPLACE`` or ``config_value::NOT_INPLACE``) | [``config_value::INPLACE``] - * - :ref:`FWD_STRIDES` - - Offset and strides defining the layout within a given data sequence - in the forward domain. + * - ``FWD_STRIDES`` + - Offset and strides :ref:`defining the layout` + within a given data sequence in the forward domain. - | ``std::vector`` of size :math:`(d+1)` - | [defined :ref:`here`] - * - :ref:`BWD_STRIDES` - - Offset and strides defining the layout within a given data sequence - in the backward domain. + | [see the :ref:`dedicated section`] + * - ``BWD_STRIDES`` + - Offset and strides :ref:`defining the layout` + within a given data sequence in the backward domain. - | ``std::vector`` of size :math:`(d+1)` - | [defined :ref:`here`] - * - :ref:`INPUT_STRIDES` (deprecated) - - Offset and strides defining the layout within a given *input* data - sequence. + | [see the :ref:`dedicated section`] + * - ``INPUT_STRIDES`` (deprecated) + - Offset and strides :ref:`defining the layout` + within a given *input* data sequence. - | ``std::vector`` of size :math:`(d+1)` | [``std::vector(d+1, 0)``] - * - :ref:`OUTPUT_STRIDES` (deprecated) - - Offset and strides defining the layout within a given *output* data - sequence. + * - ``OUTPUT_STRIDES`` (deprecated) + - Offset and strides :ref:`defining the layout` + within a given *output* data sequence. - | ``std::vector`` of size :math:`(d+1)` | [``std::vector(d+1, 0)``] - * - :ref:`FWD_DISTANCE` - - Distance in number of elements of + * - ``FWD_DISTANCE`` + - :ref:`Distance` in + number of elements of :ref:`implicitly-assumed data type` between forward-domain entries :math:`\left(\cdot\right)^{m}_{k_1, k_2, \ldots, k_d}` and @@ -251,9 +244,10 @@ the :ref:`descriptor` class. relevant (and *must* be set) for batched DFT(s), *i.e.*, if :math:`M > 1`. - | ``std::int64_t`` - | [0] - * - :ref:`BWD_DISTANCE` - - Distance in number of elements of + | [:math:`0`] + * - ``BWD_DISTANCE`` + - :ref:`Distance` in + number of elements of :ref:`implicitly-assumed data type` between backward-domain entries :math:`\left(\cdot\right)^{m}_{k_1, k_2, \ldots, k_d}` and @@ -264,48 +258,88 @@ the :ref:`descriptor` class. relevant (and *must* be set) for batched DFT(s), *i.e.*, if :math:`M > 1`. - | ``std::int64_t`` - | [0] - * - :ref:`WORKSPACE_PLACEMENT` - - Some FFT algorithm computation steps require a scratch space for permutations or other purposes. - This parameter controls whether this scratch space is automatically allocated or provided by the user. - - | :ref:`onemkl_dft_enum_config_value` (possible values are ``config_value::WORKSPACE_AUTOMATIC`` or ``config_value::WORKSPACE_EXTERNAL``). + | [:math:`0`] + * - ``WORKSPACE_PLACEMENT`` + - Some FFT algorithm computation steps require a + :ref:`scratch space` for + permutations or other purposes. This parameter controls whether this + scratch space is automatically allocated or provided by the user. + - | ``config_value`` (possible values are ``config_value::WORKSPACE_AUTOMATIC`` or ``config_value::WORKSPACE_EXTERNAL``). | [``config_value::WORKSPACE_AUTOMATIC``] - * - WORKSPACE_EXTERNAL_BYTES - - The required minimum external workspace size for use by :ref:`set_workspace`. - A read-only value, on committed descriptors only. + * - ``WORKSPACE_EXTERNAL_BYTES`` + - The required minimum external workspace size for use by the + ``set_workspace`` :ref:`member function`. + This parameter is read-only and can be queried only if the + ``descriptor`` object is committed. - | ``std::int64_t`` - + | [N/A] .. _onemkl_dft_enum_config_value: -config_value -++++++++++++ +``config_value`` +++++++++++++++++ -This scoped enumeration type represents possible non-numeric configuration -values associated with some +Values in this scoped enumeration type represent possible non-numeric +configuration values associated with some :ref:`configuration parameters`. .. container:: section .. code:: cpp - - enum class config_value { - // for config_param::COMMIT_STATUS - COMMITTED, - UNCOMMITTED, - - // for config_param::COMPLEX_STORAGE, - COMPLEX_COMPLEX, - REAL_REAL, - - // for config_param::PLACEMENT - INPLACE, - NOT_INPLACE - - // For config_param::WORKSPACE_PLACEMENT - WORKSPACE_AUTOMATIC, - WORKSPACE_EXTERNAL, - }; + + namespace oneapi::mkl::dft { + enum class config_value { + // for config_param::COMMIT_STATUS + COMMITTED, + UNCOMMITTED, + + // for config_param::COMPLEX_STORAGE, + COMPLEX_COMPLEX, + REAL_REAL, + + // for config_param::PLACEMENT + INPLACE, + NOT_INPLACE + + // For config_param::WORKSPACE_PLACEMENT + WORKSPACE_AUTOMATIC, + WORKSPACE_EXTERNAL, + }; + } + + + .. list-table:: + :header-rows: 1 + :widths: 30 67 + + * - ``config_value`` enumerators + - Description + * - | ``COMMITTED`` + | ``UNCOMMITTED`` + - Possible configuration values associated with the configuration + parameter ``config_param::COMMIT_STATUS`` indicating whether a + ``descriptor`` object was successfully commited + (``config_value::COMMITTED``) or not (``config_value::UNCOMMITTED``). + * - | ``COMPLEX_COMPLEX`` + | ``REAL_REAL`` + - Possible configuration values associated with the configuration + parameter ``config_param::COMPLEX_STORAGE`` indicating whether real + and imaginary parts of complex entries are stored separately + (``config_value::REAL_REAL``) or not (``config_value::COMPLEX_COMPLEX``). + More details are available in the page dedicated to + :ref:`data storage`. + * - | ``INPLACE`` + | ``NOT_INPLACE`` + - Possible configuration values associated with the configuration + parameter ``config_param::PLACEMENT`` indicating whether the DFT + computation must be performed in-place (``config_value::INPLACE``) + or not (``config_value::NOT_INPLACE``). + * - | ``WORKSPACE_AUTOMATIC`` + | ``WORKSPACE_EXTERNAL`` + - Possible configuration values associated with the configuration + parameter ``config_param::WORKSPACE_PLACEMENT``. More details are + available in the page dedicated to + :ref:`workspace placement`. **Parent topic:** :ref:`onemkl_dft`