[oneMath][RNG] Added random engine adaptors (#616)

* added the engine adaptor

Signed-off-by: Fedorov, Andrey <[email protected]>

* fixed small error

* fixed the same mistake in one more files

* correct the link to the previous page

* added an example

* reword a bit

---------

Signed-off-by: Fedorov, Andrey <[email protected]>

Author: andreyfe1

source/elements/oneMath/source/domains/rng/device_api/device-adaptors.rst

@@ -0,0 +1,30 @@
+.. SPDX-FileCopyrightText: 2025 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _onemath_device_rng_adaptors:
+
+Engine Adaptors
+===============
+
+oneMath RNG provides following device engine adaptors:
+
+.. tabularcolumns:: |\Y{0.4}|\Y{0.6}|
+
+.. list-table::
+   :header-rows: 1
+   :class: longtable
+
+   * -  Routine
+     -  Description
+
+   * -  :ref:`onemath_device_rng_count_engine_adaptor`
+     -  Provide a method to count how many random numbers were taken from an
+        engine during the ``generate`` call
+
+.. toctree::
+   :hidden:
+
+   device-rng-count_engine_adaptor.rst
+
+**Parent topic:** :ref:`onemath_device_rng_routines`

source/elements/oneMath/source/domains/rng/device_api/device-rng-count_engine_adaptor.rst

@@ -0,0 +1,94 @@
+.. SPDX-FileCopyrightText: 2025 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _onemath_device_rng_count_engine_adaptor:
+
+Count Engine Adaptor
+====================
+
+``count_engine_adaptor`` is a random number engine adaptor that counts how many times
+random 32 bits were taken from the engine during the ``generate`` call.
+
+.. rubric:: Description
+
+This adaptor helps to query how many random numbers were taken from
+an engine during the ``generate`` call. Especially it's useful for distributions
+based on the acceptance-rejection algorithms, e.g. ``beta``, ``gamma``.
+
+class count_engine_adaptor
+--------------------------
+
+.. rubric:: Syntax
+
+.. code-block:: cpp
+
+   namespace oneapi::math::rng::device {
+    template <typename Engine>
+    class count_engine_adaptor {
+    public:
+        static constexpr std::int32_t vec_size = Engine::vec_size;
+
+        // ctors
+        explicit count_engine_adaptor(const Engine& engine);
+        explicit count_engine_adaptor(Engine&& engine);
+
+        template <typename... Params>
+        count_engine_adaptor(Params... params);
+
+        // getters
+        std::int64_t get_count() const;
+        const Engine& base() const;
+    };
+  }
+
+.. container:: section
+
+    .. rubric:: Class Template Parameters
+
+    Engine
+        Describes the type of the engine that ``count_engine_adaptor``
+        is constructed over.
+
+.. container:: section
+
+    .. rubric:: Class Members
+
+    .. list-table::
+        :header-rows: 1
+
+        * - Routine
+          - Description
+        * - ``explicit count_engine_adaptor(const Engine& engine)``
+          - Constructs the adaptor over ``engine``.
+        * - ``explicit count_engine_adaptor(Engine&& engine)``
+          - Constructs the adaptor over ``engine`` by moving.
+        * - ``count_engine_adaptor(Params... params)``
+          - Constructs the adaptor generating an engine inside. ``params`` is a
+            pack of input parameters to create an engine.
+        * - ``std::int64_t get_count() const``
+          - This method returns the amount of random numbers generated by ``generate``.
+        * - ``const Engine& base() const``
+          - Returns the underlying engine.
+
+.. rubric:: Example
+
+.. code-block:: cpp
+
+    namespace rng_device = oneapi::math::rng::device;
+
+    sycl::event my_event = q.parallel_for({n}, [=](std::size_t idx) {
+        // Some code...
+
+        rng_device::count_engine_adaptor<rng_device::mcg59<VecSize>> adaptor(seed, idx);
+        r[idx] = rng_device::generate(distr, adaptor);
+
+        consumed[idx] = adaptor.get_count();
+
+        // continue work with engine if needed
+        auto engine = adaptor.base();
+        // ...
+    });
+
+
+**Parent topic:** :ref:`onemath_device_rng_adaptors`

source/elements/oneMath/source/domains/rng/device_api/device-routines.rst

@@ -23,17 +23,20 @@ The main purpose of Device routines is to make them callable from your SYCL kern
 
 .. rubric:: Structure
 
-RNG domain contains two classes types:
+RNG domain contains three classes types:
 
    -  Engines (basic random number generators) classes, which holds
-      the state of generator and is a source of independent and identically distributed random variables. 
+      the state of generator and is a source of independent and identically distributed random variables.
       Refer to :ref:`onemath_rng_engines_basic_random_number_generators`
       for a detailed description.
    -  Distribution classes templates (transformation classes) for different types of statistical
       distributions, for example, uniform, normal (Gaussian), binomial,
-      etc. These classes contain all of the distribution’s parameters
+      etc. These classes contain all of the distribution's parameters
       (including generation method). Refer to :ref:`onemath_device_rng_distributions` for
       a detailed description of the distributions.
+   -  Engine adaptors classes are wrappers over random number generators that provide extra functionality,
+      e.g. count engine adaptor. Refer to :ref:`onemath_device_rng_adaptors` for
+      a detailed description.
 
 The RNG domain also contains two types of free functions:
 
@@ -56,7 +59,8 @@ section for the description of typical RNG scenario.
    device-rng-generate-routines.rst
    device-engines.rst
    device-distributions.rst
+   device-adaptors.rst
    device-service-routines.rst
    ../bibliography.rst
 
-**Parent topic:** :ref:`onemath_rng`
+**Parent topic:** :ref:`onemath_rng_overview`

source/elements/oneMath/source/domains/rng/host_api/rng-host-routines.rst

@@ -12,7 +12,7 @@ Random Number Generators Host Routines
 RNG domain contains two classes types:
 
    -  Engines (basic random number generators) classes, which holds
-      the state of generator and is a source of independent and identically distributed random variables. 
+      the state of generator and is a source of independent and identically distributed random variables.
       Refer to :ref:`onemath_rng_engines_basic_random_number_generators`
       for a detailed description.
    -  Distribution classes templates (transformation classes) for different types of statistical
@@ -45,4 +45,4 @@ section for the description of typical RNG scenario.
    distributions.rst
    ../bibliography.rst
 
-**Parent topic:** :ref:`onemath_rng`
+**Parent topic:** :ref:`onemath_rng_overview`