Skip to content

Commit 84645e3

Browse files
andreyfe1andreyfe1
authored
[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
1 parent 72362f3 commit 84645e3

File tree

8 files changed

+519
-28
lines changed

8 files changed

+519
-28
lines changed

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

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -20,22 +20,22 @@ Distributions Template Parameter Method
2020
* - ``uniform_method::standard``
2121
``uniform_method::accurate``
2222
- ``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
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
2525
``uniform_method::standard`` method on GPU).
2626
* - ``gaussian_method::box_muller2``
2727
- ``gaussian``
28-
- Generates normally distributed random numbers `x1` and `x2` through the pair of uniformly distributed numbers `u1` and `u2` according to
28+
- Generates normally distributed random numbers `x1` and `x2` through the pair of uniformly distributed numbers `u1` and `u2` according to
2929
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}`\
3030
* - ``exponential_method::icdf``
3131
``exponential_method::icdf_accurate``
3232
- ``exponential``
3333
- Inverse cumulative distribution function (ICDF) method.
3434
* - ``lognormal_method::box_muller2``
3535
- ``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-
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+
3939
Then `x1` and `x2` are converted to lognormal distribution.
4040
* - ``bernoulli_method::icdf``
4141
- ``bernoulli``
@@ -49,4 +49,4 @@ Distributions Template Parameter Method
4949
* Left exponential tail
5050
* Right exponential tail
5151

52-
`NOTE:` Methods provided for exposition purposes.
52+
`NOTE:` Methods provided for exposition purposes.

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

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,11 @@
77
Device Distributions
88
====================
99

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
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
1515
basic random number generators.
1616

1717
**Device Continuous Distribution Generators**
@@ -39,6 +39,14 @@ basic random number generators.
3939
- float, double
4040
- float, double
4141
- Lognormal distribution
42+
* - :ref:`onemkl_device_rng_beta`
43+
- float, double
44+
- float, double
45+
- Beta distribution
46+
* - :ref:`onemkl_device_rng_gamma`
47+
- float, double
48+
- float, double
49+
- Gamma distribution
4250

4351

4452
**Device Discrete Distribution Generators**
@@ -89,4 +97,6 @@ basic random number generators.
8997
device-rng-uniform-bits.rst
9098
device-rng-poisson.rst
9199
device-rng-bernoulli.rst
100+
device-rng-beta.rst
101+
device-rng-gamma.rst
92102

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

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
.. SPDX-FileCopyrightText: 2024 Intel Corporation
2+
..
3+
.. SPDX-License-Identifier: CC-BY-4.0
4+
5+
.. _onemkl_device_rng_beta:
6+
7+
beta
8+
====
9+
10+
11+
Generates beta distributed random numbers.
12+
13+
.. rubric:: Description
14+
15+
The ``beta`` class object is used in the ``generate`` function to provide
16+
random numbers with beta distribution that has shape parameters :math:`p` and :math:`q`,
17+
displacement :math:`\alpha` and scale parameter :math:`(b, \beta)`, where :math:`p`, :math:`q`.
18+
:math:`\alpha`, :math:`\beta` :math:`\in R; p > 0; q > 0; \beta > 0`.
19+
20+
The probability distribution is given by:
21+
22+
.. math::
23+
24+
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.
25+
26+
The cumulative distribution function is as follows:
27+
28+
.. math::
29+
30+
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.
31+
32+
33+
Where :math:`B(p, 1)` is the complete beta function.
34+
35+
class beta
36+
----------
37+
38+
.. rubric:: Syntax
39+
40+
.. code-block:: cpp
41+
42+
namespace oneapi::mkl::rng::device {
43+
template<typename RealType, typename Method>
44+
class beta {
45+
public:
46+
using method_type = Method;
47+
using result_type = RealType;
48+
49+
beta();
50+
explicit beta(RealType p, RealType q, RealType a, RealType b);
51+
52+
RealType p() const;
53+
RealType q() const;
54+
RealType a() const;
55+
RealType b() const;
56+
std::size_t count_rejected_numbers() const;
57+
};
58+
}
59+
60+
61+
.. container:: section
62+
63+
.. rubric:: Template parameters
64+
65+
.. container:: section
66+
67+
typename RealType
68+
Type of the produced values. Supported types:
69+
70+
* ``float``
71+
* ``double``
72+
73+
.. container:: section
74+
75+
typename Method
76+
Generation method. The type is unspecified.
77+
78+
79+
.. container:: section
80+
81+
.. rubric:: Class Members
82+
83+
.. list-table::
84+
:header-rows: 1
85+
86+
* - Routine
87+
- Description
88+
* - `beta()`_
89+
- Default constructor
90+
* - `explicit beta(RealType p, RealType q, RealType a, RealType b)`_
91+
- Constructor with parameters
92+
* - `RealType p() const`_
93+
- Method to obtain shape ``p``
94+
* - `RealType q() const`_
95+
- Method to obtain shape ``q``
96+
* - `RealType a() const`_
97+
- Method to obtain displacement :math:`\alpha`
98+
* - `RealType b() const`_
99+
- Method to obtain scale parameter :math:`\beta`
100+
* - `size_t count_rejected_numbers() const`_
101+
- Method to obtain amount of random numbers that were rejected during
102+
the last ``generate`` function call. If no ``generate`` calls, ``0`` is returned.
103+
104+
.. container:: section
105+
106+
.. rubric:: Member types
107+
108+
.. container:: section
109+
110+
.. code-block:: cpp
111+
112+
beta::method_type = Method
113+
114+
.. container:: section
115+
116+
.. rubric:: Description
117+
118+
The type which defines transformation method for generation.
119+
120+
.. container:: section
121+
122+
.. code-block:: cpp
123+
124+
beta::result_type = RealType
125+
126+
.. container:: section
127+
128+
.. rubric:: Description
129+
130+
The type which defines type of generated random numbers.
131+
132+
.. container:: section
133+
134+
.. rubric:: Constructors
135+
136+
.. container:: section
137+
138+
.. _`beta()`:
139+
140+
.. code-block:: cpp
141+
142+
beta::beta()
143+
144+
.. container:: section
145+
146+
.. rubric:: Description
147+
148+
Default constructor for distribution, parameters set as
149+
``p`` = 1.0, ``q`` = 1.0, :math:`\alpha` = 0.0, :math:`\beta` = 1.0.
150+
151+
.. container:: section
152+
153+
.. _`explicit beta(RealType p, RealType q, RealType a, RealType b)`:
154+
155+
.. code-block:: cpp
156+
157+
explicit beta::beta(RealType p, RealType q, RealType a, RealType b)
158+
159+
.. container:: section
160+
161+
.. rubric:: Description
162+
163+
Constructor with parameters. ``p`` and ``q`` are shapes, :math:`\alpha` is a displacement, :math:`\beta` is a scale parameter.
164+
165+
.. container:: section
166+
167+
.. rubric:: Throws
168+
169+
oneapi::mkl::invalid_argument
170+
Exception is thrown when :math:`p \leq 0`, or :math:`q \leq 0`, or :math:`\beta \leq 0`
171+
172+
.. container:: section
173+
174+
.. rubric:: Characteristics
175+
176+
.. container:: section
177+
178+
.. _`RealType p() const`:
179+
180+
.. code-block:: cpp
181+
182+
RealType beta::p() const
183+
184+
.. container:: section
185+
186+
.. rubric:: Return Value
187+
188+
Returns the distribution parameter ``p`` - shape.
189+
190+
.. container:: section
191+
192+
.. _`RealType q() const`:
193+
194+
.. code-block:: cpp
195+
196+
RealType beta::q() const
197+
198+
.. container:: section
199+
200+
.. rubric:: Return Value
201+
202+
Returns the distribution parameter ``q`` - shape.
203+
204+
.. container:: section
205+
206+
.. _`RealType a() const`:
207+
208+
.. code-block:: cpp
209+
210+
RealType beta::a() const
211+
212+
.. container:: section
213+
214+
.. rubric:: Return Value
215+
216+
Returns the distribution parameter :math:`\alpha` - displacement.
217+
218+
.. container:: section
219+
220+
.. _`RealType b() const`:
221+
222+
.. code-block:: cpp
223+
224+
RealType beta::b() const
225+
226+
.. container:: section
227+
228+
.. rubric:: Return Value
229+
230+
Returns the distribution parameter :math:`\beta` - scale parameter value.
231+
232+
.. container:: section
233+
234+
.. _`size_t count_rejected_numbers() const`:
235+
236+
.. code-block:: cpp
237+
238+
std::size_t beta::count_rejected_numbers() const
239+
240+
.. container:: section
241+
242+
.. rubric:: Return Value
243+
244+
Returns the amount of random numbers that were rejected during
245+
the last ``generate`` function call. If no ``generate`` calls, ``0`` is returned.
246+
247+
**Parent topic:** :ref:`onemkl_device_rng_distributions`

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Generates exponentially distributed random numbers.
1212

1313
.. rubric:: Description
1414

15-
The ``exponential`` class object is used in the ``generate`` function to provide
15+
The ``exponential`` class object is used in the ``generate`` function to provide
1616
random numbers with exponential distribution that has displacement :math:`a` and scalefactor :math:`\beta`,
1717
where :math:`a, \beta \in R ; \beta > 0`.
1818

@@ -53,10 +53,10 @@ class exponential
5353
public:
5454
using method_type = Method;
5555
using result_type = RealType;
56-
56+
5757
exponential();
5858
explicit exponential(RealType a, RealType beta);
59-
59+
6060
RealType a() const;
6161
RealType beta() const;
6262
};
@@ -113,7 +113,7 @@ class exponential
113113

114114
.. code-block:: cpp
115115
116-
lognormal::method_type = Method
116+
exponential::method_type = Method
117117
118118
.. container:: section
119119

@@ -125,7 +125,7 @@ class exponential
125125

126126
.. code-block:: cpp
127127
128-
lognormal::result_type = RealType
128+
exponential::result_type = RealType
129129
130130
.. container:: section
131131

@@ -204,4 +204,4 @@ class exponential
204204

205205
Returns the distribution parameter `beta` - scalefactor value.
206206

207-
**Parent topic:** :ref:`onemkl_device_rng_distributions`
207+
**Parent topic:** :ref:`onemkl_device_rng_distributions`

0 commit comments

Comments
 (0)