[oneMKL][RNG][Spec] Added oneMKL RNG Device APIs (#493)

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`
+