[oneMKL][RNG] Add 2 distributions to Device API: beta, gamma. (#559)

* added gamma distribution

* small naming improvement

* added beta distribution

* added new methods to the separate page

* unspecify methods

* added files to toctree

* fixed error in beta parameters

source/elements/oneMKL/source/domains/rng/device_api/device-distributions-template-parameter-method.rst

@@ -20,22 +20,22 @@ Distributions Template Parameter Method
    * -  ``uniform_method::standard``
         ``uniform_method::accurate``
      -  ``uniform``
-     -   Standard method. ``uniform_method::accurate`` checks for additional ``float`` and ``double`` data types. 
-         For ``integer`` data types, it uses ``double`` as a ``BRNG`` data type (``float`` ``BRNG`` data type is used in 
+     -   Standard method. ``uniform_method::accurate`` checks for additional ``float`` and ``double`` data types.
+         For ``integer`` data types, it uses ``double`` as a ``BRNG`` data type (``float`` ``BRNG`` data type is used in
          ``uniform_method::standard`` method on GPU).
    * -  ``gaussian_method::box_muller2``
      -  ``gaussian``
-     -  Generates normally distributed random numbers `x1` and `x2` through the pair of uniformly distributed numbers `u1` and `u2` according to 
+     -  Generates normally distributed random numbers `x1` and `x2` through the pair of uniformly distributed numbers `u1` and `u2` according to
         the formulas: :math:`x_1 = \sqrt{-2 \ln u_1} \sin {2 \pi u_2}`\ :math:`x_2 = \sqrt{-2 \ln u_1} \cos {2 \pi u_2}`\
    * -  ``exponential_method::icdf``
         ``exponential_method::icdf_accurate``
      -  ``exponential``
      -  Inverse cumulative distribution function (ICDF) method.
    * -  ``lognormal_method::box_muller2``
      -  ``lognormal``
-     -  Normally distributed random numbers `x1` and `x2` are produced through the pair of uniformly distributed numbers `u1` and `u2` according to the formulas: 
-        :math:`x_1 = -2 \ln u_1 \sin {2 \pi u_2}`\       \ :math:`x_2 = -2 \ln u_1 \cos {2 \pi u_2}`\   
-        
+     -  Normally distributed random numbers `x1` and `x2` are produced through the pair of uniformly distributed numbers `u1` and `u2` according to the formulas:
+        :math:`x_1 = -2 \ln u_1 \sin {2 \pi u_2}`\       \ :math:`x_2 = -2 \ln u_1 \cos {2 \pi u_2}`\
+
         Then `x1` and `x2` are converted to lognormal distribution.
    * -  ``bernoulli_method::icdf``
      -  ``bernoulli``
@@ -49,4 +49,4 @@ Distributions Template Parameter Method
         * Left exponential tail
         * Right exponential tail
 
-`NOTE:` Methods provided for exposition purposes. 
+`NOTE:` Methods provided for exposition purposes.

source/elements/oneMKL/source/domains/rng/device_api/device-distributions.rst

@@ -7,11 +7,11 @@
 Device Distributions
 ====================
 
-oneMKL RNG routines are used to generate random numbers with different types of distributions. Each function group is 
-introduced below by the type of underlying distribution and contains a short description of its functionality, as well 
-as specifications of the call sequence and the explanation of input and output parameters. The Device Continuous 
-Distribution Generators table and Device Discrete Distribution Generators table mention random number generator routines 
-with data types and output distributions, and sets correspondence between data types of the generator routines and the 
+oneMKL RNG routines are used to generate random numbers with different types of distributions. Each function group is
+introduced below by the type of underlying distribution and contains a short description of its functionality, as well
+as specifications of the call sequence and the explanation of input and output parameters. The Device Continuous
+Distribution Generators table and Device Discrete Distribution Generators table mention random number generator routines
+with data types and output distributions, and sets correspondence between data types of the generator routines and the
 basic random number generators.
 
 **Device Continuous Distribution Generators**
@@ -39,6 +39,14 @@ basic random number generators.
      -     float, double
      -     float, double
      -     Lognormal distribution
+   * -     :ref:`onemkl_device_rng_beta`
+     -     float, double
+     -     float, double
+     -     Beta distribution
+   * -     :ref:`onemkl_device_rng_gamma`
+     -     float, double
+     -     float, double
+     -     Gamma distribution
 
 
 **Device Discrete Distribution Generators**
@@ -89,4 +97,6 @@ basic random number generators.
    device-rng-uniform-bits.rst
    device-rng-poisson.rst
    device-rng-bernoulli.rst
+   device-rng-beta.rst
+   device-rng-gamma.rst
 

source/elements/oneMKL/source/domains/rng/device_api/device-rng-beta.rst

@@ -0,0 +1,247 @@
+.. SPDX-FileCopyrightText: 2024 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _onemkl_device_rng_beta:
+
+beta
+====
+
+
+Generates beta distributed random numbers.
+
+.. rubric:: Description
+
+The ``beta`` class object is used in the ``generate`` function to provide
+random numbers with beta distribution that has shape parameters :math:`p` and :math:`q`,
+displacement :math:`\alpha` and scale parameter :math:`(b, \beta)`, where :math:`p`, :math:`q`.
+:math:`\alpha`, :math:`\beta` :math:`\in R; p > 0; q > 0; \beta > 0`.
+
+The probability distribution is given by:
+
+.. math::
+
+    f_{p, q, \alpha, \beta}(x) = \left\{ \begin{array}{rcl} \frac{1}{B(p, q) * \beta^{p + q - 1}}(x - a)^{p - 1}*(\beta + \alpha - x)^{q - 1}, \alpha \leq x < \alpha + \beta \\ 0, x < \alpha, x \ge \alpha + \beta \end{array}\right.
+
+The cumulative distribution function is as follows:
+
+.. math::
+
+    F_{a, b}(x) = \left\{ \begin{array}{rcl} 0, x < \alpha \\ \int^x_{\alpha}\frac{1}{B(p, q) * \beta^{p + q - 1}}(y - \alpha)^{p - 1}*(\beta + \alpha - y)^{q - 1}dy, \alpha \leq x < \alpha + \beta, x \in R \\ 1, x \ge \alpha + \beta \end{array}\right.
+
+
+Where :math:`B(p, 1)` is the complete beta function.
+
+class beta
+----------
+
+.. rubric:: Syntax
+
+.. code-block:: cpp
+
+   namespace oneapi::mkl::rng::device {
+     template<typename RealType, typename Method>
+     class beta {
+     public:
+       using method_type = Method;
+       using result_type = RealType;
+
+       beta();
+       explicit beta(RealType p, RealType q, RealType a, RealType b);
+
+       RealType p() const;
+       RealType q() const;
+       RealType a() const;
+       RealType b() const;
+       std::size_t count_rejected_numbers() const;
+     };
+   }
+
+
+.. container:: section
+
+    .. rubric:: Template parameters
+
+    .. container:: section
+
+        typename RealType
+            Type of the produced values. Supported types:
+
+                * ``float``
+                * ``double``
+
+    .. container:: section
+
+        typename Method
+            Generation method. The type is unspecified.
+
+
+.. container:: section
+
+    .. rubric:: Class Members
+
+    .. list-table::
+        :header-rows: 1
+
+        * - Routine
+          - Description
+        * - `beta()`_
+          - Default constructor
+        * - `explicit beta(RealType p, RealType q, RealType a, RealType b)`_
+          - Constructor with parameters
+        * - `RealType p() const`_
+          - Method to obtain shape ``p``
+        * - `RealType q() const`_
+          - Method to obtain shape ``q``
+        * - `RealType a() const`_
+          - Method to obtain displacement :math:`\alpha`
+        * - `RealType b() const`_
+          - Method to obtain scale parameter :math:`\beta`
+        * - `size_t count_rejected_numbers() const`_
+          - Method to obtain amount of random numbers that were rejected during
+            the last ``generate`` function call. If no ``generate`` calls, ``0`` is returned.
+
+.. container:: section
+
+    .. rubric:: Member types
+
+    .. container:: section
+
+        .. code-block:: cpp
+
+            beta::method_type = Method
+
+        .. container:: section
+
+            .. rubric:: Description
+
+            The type which defines transformation method for generation.
+
+    .. container:: section
+
+        .. code-block:: cpp
+
+            beta::result_type = RealType
+
+        .. container:: section
+
+            .. rubric:: Description
+
+            The type which defines type of generated random numbers.
+
+.. container:: section
+
+    .. rubric:: Constructors
+
+    .. container:: section
+
+        .. _`beta()`:
+
+        .. code-block:: cpp
+
+            beta::beta()
+
+        .. container:: section
+
+            .. rubric:: Description
+
+            Default constructor for distribution, parameters set as
+            ``p`` = 1.0, ``q`` = 1.0, :math:`\alpha` = 0.0, :math:`\beta` = 1.0.
+
+    .. container:: section
+
+        .. _`explicit beta(RealType p, RealType q, RealType a, RealType b)`:
+
+        .. code-block:: cpp
+
+            explicit beta::beta(RealType p, RealType q, RealType a, RealType b)
+
+        .. container:: section
+
+            .. rubric:: Description
+
+            Constructor with parameters. ``p`` and ``q`` are shapes, :math:`\alpha` is a displacement, :math:`\beta` is a scale parameter.
+
+        .. container:: section
+
+            .. rubric:: Throws
+
+            oneapi::mkl::invalid_argument
+                Exception is thrown when :math:`p \leq 0`, or :math:`q \leq 0`, or :math:`\beta \leq 0`
+
+.. container:: section
+
+    .. rubric:: Characteristics
+
+    .. container:: section
+
+        .. _`RealType p() const`:
+
+        .. code-block:: cpp
+
+            RealType beta::p() const
+
+        .. container:: section
+
+            .. rubric:: Return Value
+
+            Returns the distribution parameter ``p`` - shape.
+
+    .. container:: section
+
+        .. _`RealType q() const`:
+
+        .. code-block:: cpp
+
+            RealType beta::q() const
+
+        .. container:: section
+
+            .. rubric:: Return Value
+
+            Returns the distribution parameter ``q`` - shape.
+
+    .. container:: section
+
+        .. _`RealType a() const`:
+
+        .. code-block:: cpp
+
+            RealType beta::a() const
+
+        .. container:: section
+
+            .. rubric:: Return Value
+
+            Returns the distribution parameter :math:`\alpha` - displacement.
+
+    .. container:: section
+
+        .. _`RealType b() const`:
+
+        .. code-block:: cpp
+
+            RealType beta::b() const
+
+        .. container:: section
+
+            .. rubric:: Return Value
+
+            Returns the distribution parameter :math:`\beta` - scale parameter value.
+
+    .. container:: section
+
+        .. _`size_t count_rejected_numbers() const`:
+
+        .. code-block:: cpp
+
+            std::size_t beta::count_rejected_numbers() const
+
+        .. container:: section
+
+            .. rubric:: Return Value
+
+            Returns the amount of random numbers that were rejected during
+            the last ``generate`` function call. If no ``generate`` calls, ``0`` is returned.
+
+**Parent topic:** :ref:`onemkl_device_rng_distributions`

source/elements/oneMKL/source/domains/rng/device_api/device-rng-exponential.rst

@@ -12,7 +12,7 @@ Generates exponentially distributed random numbers.
 
 .. rubric:: Description
 
-The ``exponential`` class object is used in the ``generate`` function to provide 
+The ``exponential`` class object is used in the ``generate`` function to provide
 random numbers with exponential distribution that has displacement :math:`a` and scalefactor :math:`\beta`,
 where :math:`a, \beta \in R ; \beta > 0`.
 
@@ -53,10 +53,10 @@ class exponential
      public:
        using method_type = Method;
        using result_type = RealType;
-  
+
        exponential();
        explicit exponential(RealType a, RealType beta);
-  
+
        RealType a() const;
        RealType beta() const;
      };
@@ -113,7 +113,7 @@ class exponential
 
         .. code-block:: cpp
 
-            lognormal::method_type = Method
+            exponential::method_type = Method
 
         .. container:: section
 
@@ -125,7 +125,7 @@ class exponential
 
         .. code-block:: cpp
 
-            lognormal::result_type = RealType
+            exponential::result_type = RealType
 
         .. container:: section
 
@@ -204,4 +204,4 @@ class exponential
 
             Returns the distribution parameter `beta` - scalefactor value.
 
-**Parent topic:** :ref:`onemkl_device_rng_distributions`
+**Parent topic:** :ref:`onemkl_device_rng_distributions`