[oneMKL][RNG][Spec] Added oneMKL RNG Device APIs

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

@@ -0,0 +1,52 @@
+.. SPDX-FileCopyrightText: 2023 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _onemkl_device_rng_distributions_method:
+
+Distributions Template Parameter Method
+=======================================
+
+.. tabularcolumns:: |\Y{0.4}|\Y{0.2}|\Y{0.4}|
+
+.. list-table::
+   :header-rows: 1
+   :class: longtable
+
+   * -  Method Type
+     -  Distributions
+     -  Math Description
+
+   * -  ``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 
+         ``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 
+        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}`\   
+
+        Then `x1` and `x2` are converted to lognormal distribution.
+   * -  ``bernoulli_method::icdf``
+     -  ``bernoulli``
+     -  Inverse cumulative distribution function (ICDF) method.
+   * -  ``poisson_method::devroye``
+     -  ``poisson``
+     -  Acceptance/rejection method for :math:`\lambda \geq 27` with decomposition into four regions:
+
+        * Two parallelograms
+        * Triangle
+        * Left exponential tail
+        * Right exponential tail
+
+`NOTE:` Methods provided for exposition purposes. 

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

@@ -0,0 +1,92 @@
+.. SPDX-FileCopyrightText: 2023 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _onemkl_device_rng_distributions:
+
+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 
+basic random number generators.
+
+**Device Continuous Distribution Generators**
+
+.. list-table::
+   :header-rows: 1
+
+   * -     Type of Distribution
+     -     Data Types
+     -     BRNG Data Type
+     -     Description
+   * -     :ref:`onemkl_device_rng_uniform_continuous`
+     -     float, double
+     -     float, double
+     -     Uniform continuous distribution on the interval [``a,b``)
+   * -     :ref:`onemkl_device_rng_gaussian`
+     -     float, double
+     -     float, double
+     -     Normal (Gaussian) distribution
+   * -     :ref:`onemkl_device_rng_exponential`
+     -     float, double
+     -     float, double
+     -     Exponential distribution
+   * -     :ref:`onemkl_device_rng_lognormal`
+     -     float, double
+     -     float, double
+     -     Lognormal distribution
+
+
+**Device Discrete Distribution Generators**
+
+.. list-table::
+   :header-rows: 1
+
+   * -     Type of Distribution
+     -     Data Types
+     -     BRNG Data Type
+     -     Description
+   * -     :ref:`onemkl_device_rng_uniform_discrete`
+     -     integer
+     -     float
+     -     Uniform discrete distribution on the interval [``a,b``)
+   * -     :ref:`onemkl_device_rng_bits`
+     -     integer
+     -     integer
+     -     Bits of underlying BRNG integer sequence
+   * -     :ref:`onemkl_device_rng_uniform_bits`
+     -     integer
+     -     integer
+     -     Uniformly distributed bits in 32/64-bit chunks
+   * -     :ref:`onemkl_device_rng_poisson`
+     -     integer
+     -     integer
+     -     Poisson distribution
+   * -     :ref:`onemkl_device_rng_bernoulli`
+     -     integer
+     -     integer
+     -     Bernoulli distribution
+
+`NOTE:` In case of ``integer`` check desired distribution for supported data types.
+
+**Parent topic:** :ref:`onemkl_device_rng_routines`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   device-distributions-template-parameter-method.rst
+   device-rng-uniform-continuous.rst
+   device-rng-gaussian.rst
+   device-rng-lognormal.rst
+   device-rng-exponential.rst
+   device-rng-uniform-discrete.rst
+   device-rng-bits.rst
+   device-rng-uniform-bits.rst
+   device-rng-poisson.rst
+   device-rng-bernoulli.rst
+

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

@@ -0,0 +1,42 @@
+.. SPDX-FileCopyrightText: 2023 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _onemkl_device_rng_engines:
+
+Device Engines (Basic Random Number Generators)
+===============================================
+
+oneMKL RNG provides following device pseudorandom number generators:
+
+.. tabularcolumns:: |\Y{0.4}|\Y{0.6}|
+
+.. list-table::
+   :header-rows: 1
+   :class: longtable
+
+   * -  Routine
+     -  Description
+
+   * -  :ref:`onemkl_device_rng_mrg32k3a`
+     -  The combined multiple recursive pseudorandom number generator ``MRG32k3a`` [:ref:`L'Ecuyer99 <onemkl_rng_bibliography>`]
+
+   * -  :ref:`onemkl_device_rng_philox4x32x10`
+     -  Philox4x32-10 counter-based pseudorandom number generator with a period of :math:`2^{128}` ``PHILOX4X32X10`` [:ref:`Salmon11 <onemkl_rng_bibliography>`]
+
+   * -  :ref:`onemkl_device_rng_mcg31m1`
+     -  The 31-bit multiplicative congruential pseudorandom number generator MCG(:math:`1132489760, 2^{32}-1`) :ref:`[L'Ecuyer99a] <onemkl_rng_bibliography>`.
+
+   * -  :ref:`onemkl_device_rng_mcg59`
+     -  The 59-bit multiplicative congruential pseudorandom number generator MCG(:math:`13^{13}, 2^{59}`) from NAG Numerical Libraries :ref:`[NAG] <onemkl_rng_bibliography>`.
+
+**Parent topic:** :ref:`onemkl_device_rng_routines`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   device-rng-mrg32k3a.rst
+   device-rng-philox4x32x10.rst
+   device-rng-mcg31m1.rst
+   device-rng-mcg59.rst

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

@@ -0,0 +1,185 @@
+.. SPDX-FileCopyrightText: 2023 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _onemkl_device_rng_bernoulli:
+
+bernoulli
+=========
+
+Generates Bernoulli distributed random values.
+
+.. rubric:: Description
+
+The ``bernoulli`` class object is used in the ``generate`` and function
+to provide Bernoulli distributed random numbers with probability ``p`` of a single trial success,
+where :math:`p \in R; 0 \leq p \leq 1`.
+
+The probability distribution is given by:
+
+.. math::
+
+    P(X = 1) = p
+
+.. math::
+
+    P(X = 0) = 1 - p
+
+The cumulative distribution function is as follows:
+
+.. math::
+
+   F_p(x) =
+   \begin{cases}
+      0, & x < 0 \\
+      1 - p, & 0 \leq x < 1, x \in R \\
+      1, & x \geq 1
+   \end{cases}
+
+
+class bernoulli
+---------------
+
+.. rubric:: Syntax
+
+.. code-block:: cpp
+
+   namespace oneapi::mkl::rng::device {
+     template<typename IntType, typename Method>
+     class bernoulli {
+     public:
+       using method_type = Method;
+       using result_type = IntType;
+
+       bernoulli();
+       explicit bernoulli(float p);
+
+       float p() const;
+     };
+   }
+
+
+.. container:: section
+
+    .. rubric:: Template parameters
+
+    .. container:: section
+
+        typename IntType
+            Type of the produced values. Supported types:
+                * ``std::int32_t``
+                * ``std::uint32_t``
+
+    .. container:: section
+
+        typename Method = oneapi::mkl::rng::bernoulli_method::by_default
+            Transformation method, which will be used for generation. Supported types:
+
+                * ``oneapi::mkl::rng::bernoulli_method::by_default``
+                * ``oneapi::mkl::rng::bernoulli_method::icdf``
+
+            See description of the methods in :ref:`Distributions methods template parameter<onemkl_rng_distributions_template_parameter_mkl_rng_method_values>`.
+
+.. container:: section
+
+    .. rubric:: Class Members
+
+    .. list-table::
+        :header-rows: 1
+
+        * - Routine
+          - Description
+        * - `bernoulli()`_
+          - Default constructor
+        * - `explicit bernoulli(float p)`_
+          - Constructor with parameters
+        * - `float p() const`_
+          - Method to obtain probability `p`
+
+.. container:: section
+
+    .. rubric:: Member types
+
+    .. container:: section
+
+        .. code-block:: cpp
+
+            bernoulli::method_type = Method
+
+        .. container:: section
+
+            .. rubric:: Description
+
+            The type which defines transformation method for generation.
+
+    .. container:: section
+
+        .. code-block:: cpp
+
+            bernoulli::result_type = IntType
+
+        .. container:: section
+
+            .. rubric:: Description
+
+            The type which defines type of generated random numbers.
+
+.. container:: section
+
+    .. rubric:: Constructors
+
+    .. container:: section
+
+        .. _`bernoulli()`:
+
+        .. code-block:: cpp
+
+            bernoulli::bernoulli()
+
+        .. container:: section
+
+            .. rubric:: Description
+
+            Default constructor for distribution, parameters set as `p` = 0.5f.
+
+    .. container:: section
+
+        .. _`explicit bernoulli(float p)`:
+
+        .. code-block:: cpp
+
+            explicit bernoulli::bernoulli(float p)
+
+        .. container:: section
+
+            .. rubric:: Description
+
+            Constructor with parameters. `p` is a probability.
+
+        .. container:: section
+
+            .. rubric:: Throws
+
+            oneapi::mkl::invalid_argument
+                Exception is thrown when `p > 1`, or `p < 0`
+
+.. container:: section
+
+    .. rubric:: Characteristics
+
+    .. container:: section
+
+        .. _`float p() const`:
+
+        .. code-block:: cpp
+
+            float bernoulli::p() const
+
+        .. container:: section
+
+            .. rubric:: Return Value
+
+            Returns the distribution parameter `p` - probability.
+
+**Parent topic:** :ref:`onemkl_device_rng_distributions`
+