Skip to content

Commit e494df3

Browse files
iMartyaniMartyan
authored
[oneMKL][RNG][Spec] Added oneMKL RNG Device APIs (#493)
1 parent 84ec400 commit e494df3

File tree

72 files changed

+2829
-162
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

72 files changed

+2829
-162
lines changed

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

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
.. SPDX-FileCopyrightText: 2023 Intel Corporation
2+
..
3+
.. SPDX-License-Identifier: CC-BY-4.0
4+
5+
.. _onemkl_device_rng_distributions_method:
6+
7+
Distributions Template Parameter Method
8+
=======================================
9+
10+
.. tabularcolumns:: |\Y{0.4}|\Y{0.2}|\Y{0.4}|
11+
12+
.. list-table::
13+
:header-rows: 1
14+
:class: longtable
15+
16+
* - Method Type
17+
- Distributions
18+
- Math Description
19+
20+
* - ``uniform_method::standard``
21+
``uniform_method::accurate``
22+
- ``uniform``
23+
- Standard method. ``uniform_method::accurate`` checks for additional ``float`` and ``double`` data types.
24+
For ``integer`` data types, it uses ``double`` as a ``BRNG`` data type (``float`` ``BRNG`` data type is used in
25+
``uniform_method::standard`` method on GPU).
26+
* - ``gaussian_method::box_muller2``
27+
- ``gaussian``
28+
- Generates normally distributed random numbers `x1` and `x2` through the pair of uniformly distributed numbers `u1` and `u2` according to
29+
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}`\
30+
* - ``exponential_method::icdf``
31+
``exponential_method::icdf_accurate``
32+
- ``exponential``
33+
- Inverse cumulative distribution function (ICDF) method.
34+
* - ``lognormal_method::box_muller2``
35+
- ``lognormal``
36+
- Normally distributed random numbers `x1` and `x2` are produced through the pair of uniformly distributed numbers `u1` and `u2` according to the formulas:
37+
:math:`x_1 = -2 \ln u_1 \sin {2 \pi u_2}`\ \ :math:`x_2 = -2 \ln u_1 \cos {2 \pi u_2}`\
38+
39+
Then `x1` and `x2` are converted to lognormal distribution.
40+
* - ``bernoulli_method::icdf``
41+
- ``bernoulli``
42+
- Inverse cumulative distribution function (ICDF) method.
43+
* - ``poisson_method::devroye``
44+
- ``poisson``
45+
- Acceptance/rejection method for :math:`\lambda \geq 27` with decomposition into four regions:
46+
47+
* Two parallelograms
48+
* Triangle
49+
* Left exponential tail
50+
* Right exponential tail
51+
52+
`NOTE:` Methods provided for exposition purposes.

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

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
.. SPDX-FileCopyrightText: 2023 Intel Corporation
2+
..
3+
.. SPDX-License-Identifier: CC-BY-4.0
4+
5+
.. _onemkl_device_rng_distributions:
6+
7+
Device Distributions
8+
====================
9+
10+
oneMKL RNG routines are used to generate random numbers with different types of distributions. Each function group is
11+
introduced below by the type of underlying distribution and contains a short description of its functionality, as well
12+
as specifications of the call sequence and the explanation of input and output parameters. The Device Continuous
13+
Distribution Generators table and Device Discrete Distribution Generators table mention random number generator routines
14+
with data types and output distributions, and sets correspondence between data types of the generator routines and the
15+
basic random number generators.
16+
17+
**Device Continuous Distribution Generators**
18+
19+
.. list-table::
20+
:header-rows: 1
21+
22+
* - Type of Distribution
23+
- Data Types
24+
- BRNG Data Type
25+
- Description
26+
* - :ref:`onemkl_device_rng_uniform_continuous`
27+
- float, double
28+
- float, double
29+
- Uniform continuous distribution on the interval [``a,b``)
30+
* - :ref:`onemkl_device_rng_gaussian`
31+
- float, double
32+
- float, double
33+
- Normal (Gaussian) distribution
34+
* - :ref:`onemkl_device_rng_exponential`
35+
- float, double
36+
- float, double
37+
- Exponential distribution
38+
* - :ref:`onemkl_device_rng_lognormal`
39+
- float, double
40+
- float, double
41+
- Lognormal distribution
42+
43+
44+
**Device Discrete Distribution Generators**
45+
46+
.. list-table::
47+
:header-rows: 1
48+
49+
* - Type of Distribution
50+
- Data Types
51+
- BRNG Data Type
52+
- Description
53+
* - :ref:`onemkl_device_rng_uniform_discrete`
54+
- integer
55+
- float
56+
- Uniform discrete distribution on the interval [``a,b``)
57+
* - :ref:`onemkl_device_rng_bits`
58+
- integer
59+
- integer
60+
- Bits of underlying BRNG integer sequence
61+
* - :ref:`onemkl_device_rng_uniform_bits`
62+
- integer
63+
- integer
64+
- Uniformly distributed bits in 32/64-bit chunks
65+
* - :ref:`onemkl_device_rng_poisson`
66+
- integer
67+
- integer
68+
- Poisson distribution
69+
* - :ref:`onemkl_device_rng_bernoulli`
70+
- integer
71+
- integer
72+
- Bernoulli distribution
73+
74+
`NOTE:` In case of ``integer`` check desired distribution for supported data types.
75+
76+
**Parent topic:** :ref:`onemkl_device_rng_routines`
77+
78+
.. toctree::
79+
:maxdepth: 1
80+
:hidden:
81+
82+
device-distributions-template-parameter-method.rst
83+
device-rng-uniform-continuous.rst
84+
device-rng-gaussian.rst
85+
device-rng-lognormal.rst
86+
device-rng-exponential.rst
87+
device-rng-uniform-discrete.rst
88+
device-rng-bits.rst
89+
device-rng-uniform-bits.rst
90+
device-rng-poisson.rst
91+
device-rng-bernoulli.rst
92+

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

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
.. SPDX-FileCopyrightText: 2023 Intel Corporation
2+
..
3+
.. SPDX-License-Identifier: CC-BY-4.0
4+
5+
.. _onemkl_device_rng_engines:
6+
7+
Device Engines (Basic Random Number Generators)
8+
===============================================
9+
10+
oneMKL RNG provides following device pseudorandom number generators:
11+
12+
.. tabularcolumns:: |\Y{0.4}|\Y{0.6}|
13+
14+
.. list-table::
15+
:header-rows: 1
16+
:class: longtable
17+
18+
* - Routine
19+
- Description
20+
21+
* - :ref:`onemkl_device_rng_mrg32k3a`
22+
- The combined multiple recursive pseudorandom number generator ``MRG32k3a`` [:ref:`L'Ecuyer99 <onemkl_rng_bibliography>`]
23+
24+
* - :ref:`onemkl_device_rng_philox4x32x10`
25+
- Philox4x32-10 counter-based pseudorandom number generator with a period of :math:`2^{128}` ``PHILOX4X32X10`` [:ref:`Salmon11 <onemkl_rng_bibliography>`]
26+
27+
* - :ref:`onemkl_device_rng_mcg31m1`
28+
- The 31-bit multiplicative congruential pseudorandom number generator MCG(:math:`1132489760, 2^{32}-1`) :ref:`[L'Ecuyer99a] <onemkl_rng_bibliography>`.
29+
30+
* - :ref:`onemkl_device_rng_mcg59`
31+
- The 59-bit multiplicative congruential pseudorandom number generator MCG(:math:`13^{13}, 2^{59}`) from NAG Numerical Libraries :ref:`[NAG] <onemkl_rng_bibliography>`.
32+
33+
**Parent topic:** :ref:`onemkl_device_rng_routines`
34+
35+
.. toctree::
36+
:maxdepth: 1
37+
:hidden:
38+
39+
device-rng-mrg32k3a.rst
40+
device-rng-philox4x32x10.rst
41+
device-rng-mcg31m1.rst
42+
device-rng-mcg59.rst

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

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
.. SPDX-FileCopyrightText: 2023 Intel Corporation
2+
..
3+
.. SPDX-License-Identifier: CC-BY-4.0
4+
5+
.. _onemkl_device_rng_bernoulli:
6+
7+
bernoulli
8+
=========
9+
10+
Generates Bernoulli distributed random values.
11+
12+
.. rubric:: Description
13+
14+
The ``bernoulli`` class object is used in the ``generate`` and function
15+
to provide Bernoulli distributed random numbers with probability ``p`` of a single trial success,
16+
where :math:`p \in R; 0 \leq p \leq 1`.
17+
18+
The probability distribution is given by:
19+
20+
.. math::
21+
22+
P(X = 1) = p
23+
24+
.. math::
25+
26+
P(X = 0) = 1 - p
27+
28+
The cumulative distribution function is as follows:
29+
30+
.. math::
31+
32+
F_p(x) =
33+
\begin{cases}
34+
0, & x < 0 \\
35+
1 - p, & 0 \leq x < 1, x \in R \\
36+
1, & x \geq 1
37+
\end{cases}
38+
39+
40+
class bernoulli
41+
---------------
42+
43+
.. rubric:: Syntax
44+
45+
.. code-block:: cpp
46+
47+
namespace oneapi::mkl::rng::device {
48+
template<typename IntType, typename Method>
49+
class bernoulli {
50+
public:
51+
using method_type = Method;
52+
using result_type = IntType;
53+
54+
bernoulli();
55+
explicit bernoulli(float p);
56+
57+
float p() const;
58+
};
59+
}
60+
61+
62+
.. container:: section
63+
64+
.. rubric:: Template parameters
65+
66+
.. container:: section
67+
68+
typename IntType
69+
Type of the produced values. Supported types:
70+
* ``std::int32_t``
71+
* ``std::uint32_t``
72+
73+
.. container:: section
74+
75+
typename Method = oneapi::mkl::rng::bernoulli_method::by_default
76+
Transformation method, which will be used for generation. Supported types:
77+
78+
* ``oneapi::mkl::rng::bernoulli_method::by_default``
79+
* ``oneapi::mkl::rng::bernoulli_method::icdf``
80+
81+
See description of the methods in :ref:`Distributions methods template parameter<onemkl_rng_distributions_template_parameter_mkl_rng_method_values>`.
82+
83+
.. container:: section
84+
85+
.. rubric:: Class Members
86+
87+
.. list-table::
88+
:header-rows: 1
89+
90+
* - Routine
91+
- Description
92+
* - `bernoulli()`_
93+
- Default constructor
94+
* - `explicit bernoulli(float p)`_
95+
- Constructor with parameters
96+
* - `float p() const`_
97+
- Method to obtain probability `p`
98+
99+
.. container:: section
100+
101+
.. rubric:: Member types
102+
103+
.. container:: section
104+
105+
.. code-block:: cpp
106+
107+
bernoulli::method_type = Method
108+
109+
.. container:: section
110+
111+
.. rubric:: Description
112+
113+
The type which defines transformation method for generation.
114+
115+
.. container:: section
116+
117+
.. code-block:: cpp
118+
119+
bernoulli::result_type = IntType
120+
121+
.. container:: section
122+
123+
.. rubric:: Description
124+
125+
The type which defines type of generated random numbers.
126+
127+
.. container:: section
128+
129+
.. rubric:: Constructors
130+
131+
.. container:: section
132+
133+
.. _`bernoulli()`:
134+
135+
.. code-block:: cpp
136+
137+
bernoulli::bernoulli()
138+
139+
.. container:: section
140+
141+
.. rubric:: Description
142+
143+
Default constructor for distribution, parameters set as `p` = 0.5f.
144+
145+
.. container:: section
146+
147+
.. _`explicit bernoulli(float p)`:
148+
149+
.. code-block:: cpp
150+
151+
explicit bernoulli::bernoulli(float p)
152+
153+
.. container:: section
154+
155+
.. rubric:: Description
156+
157+
Constructor with parameters. `p` is a probability.
158+
159+
.. container:: section
160+
161+
.. rubric:: Throws
162+
163+
oneapi::mkl::invalid_argument
164+
Exception is thrown when `p > 1`, or `p < 0`
165+
166+
.. container:: section
167+
168+
.. rubric:: Characteristics
169+
170+
.. container:: section
171+
172+
.. _`float p() const`:
173+
174+
.. code-block:: cpp
175+
176+
float bernoulli::p() const
177+
178+
.. container:: section
179+
180+
.. rubric:: Return Value
181+
182+
Returns the distribution parameter `p` - probability.
183+
184+
**Parent topic:** :ref:`onemkl_device_rng_distributions`
185+

0 commit comments

Comments
 (0)