forked from uxlfoundation/oneAPI-spec
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[oneMKL][RNG][Spec] Added oneMKL RNG Device APIs (uxlfoundation#493)
- Loading branch information
Showing
72 changed files
with
2,829 additions
and
162 deletions.
There are no files selected for viewing
52 changes: 52 additions & 0 deletions
52
...ource/domains/rng/device_api/device-distributions-template-parameter-method.rst
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
92 changes: 92 additions & 0 deletions
92
source/elements/oneMKL/source/domains/rng/device_api/device-distributions.rst
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
|
42 changes: 42 additions & 0 deletions
42
source/elements/oneMKL/source/domains/rng/device_api/device-engines.rst
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
185 changes: 185 additions & 0 deletions
185
source/elements/oneMKL/source/domains/rng/device_api/device-rng-bernoulli.rst
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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` | ||
Oops, something went wrong.