From c3d1cbd7c2677f108bd9456d55bfa29fab8a1212 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zolt=C3=A1n=20V=C3=B6r=C3=B6s?= Date: Sat, 13 Jan 2024 18:54:01 +0100 Subject: [PATCH] add random documentation rst file (#655) --- docs/manual/source/numpy-random.rst | 183 ++++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 docs/manual/source/numpy-random.rst diff --git a/docs/manual/source/numpy-random.rst b/docs/manual/source/numpy-random.rst new file mode 100644 index 00000000..2a3a8ca9 --- /dev/null +++ b/docs/manual/source/numpy-random.rst @@ -0,0 +1,183 @@ + +numpy.random +============ + +Random numbers drawn specific distributions can be generated by +instantiating a ``Generator`` object, and calling its methods. The +module defines the following three functions: + +1. `numpy.random.Generator.normal <#normal>`__ +2. `numpy.random.Generator.random <#random>`__ +3. `numpy.random.Generator.uniform <#uniform>`__ + +The ``Generator`` object, when instantiated, takes a single integer as +its argument. This integer is the seed, which will be fed to the 32-bit +or 64-bit routine. More details can be found under +https://www.pcg-random.org/index.html. The generator is a standard +``python`` object that keeps track of its state. + +``numpy``: https://numpy.org/doc/stable/reference/random/index.html + +normal +------ + +A random set of number from the ``normal`` distribution can be generated +by calling the generator’s ``normal`` method. The method takes three +optional arguments, ``loc=0.0``, the centre of the distribution, +``scale=1.0``, the width of the distribution, and ``size=None``, a tuple +containing the shape of the returned array. In case ``size`` is +``None``, a single floating point number is returned. + +The ``normal`` method of the ``Generator`` object is based on the +`Box-Muller +transform `__. + +``numpy``: +https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.normal.html + +.. code:: + + # code to be run in micropython + + from ulab import numpy as np + + rng = np.random.Generator(123456) + print(rng) + + # return single number from a distribution of scale 1, and location 0 + print(rng.normal()) + + print(rng.normal(loc=20.0, scale=10.0, size=(3,3))) + # same as above, with positional arguments + print(rng.normal(20.0, 10.0, (3,3))) + +.. parsed-literal:: + + Gnerator() at 0x7fa9dae05340 + -6.285246229407202 + array([[24.95816273705659, 15.2670302229426, 14.81001577336041], + [20.17589833056986, 23.14539083787544, 26.37772041367461], + [41.94894234387275, 37.11027030608206, 25.65889562100477]], dtype=float64) + array([[21.52562779033434, 12.74685887865834, 24.08404670765186], + [4.728112596365396, 7.667757906857082, 21.61576094228444], + [2.432338873595267, 27.75945683572574, 5.730827584659245]], dtype=float64) + + + + +random +------ + +A random set of number from the uniform distribution in the interval [0, +1] can be generated by calling the generator’s ``random`` method. The +method takes two optional arguments, ``size=None``, a tuple containing +the shape of the returned array, and ``out``. In case ``size`` is +``None``, a single floating point number is returned. + +``out`` can be used, if a floating point array is available. An +exception will be raised, if the array is not of ``float`` ``dtype``, or +if both ``size`` and ``out`` are supplied, and there is a conflict in +their shapes. + +If ``size`` is ``None``, a single floating point number will be +returned. + +``numpy``: +https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.random.html + +.. code:: + + # code to be run in micropython + + from ulab import numpy as np + + rng = np.random.Generator(123456) + print(rng) + + # returning new objects + print(rng.random()) + print('\n', rng.random(size=(3,3))) + + # supplying a buffer + a = np.array(range(9), dtype=np.float).reshape((3,3)) + print('\nbuffer array before:\n', a) + rng.random(out=a) + print('\nbuffer array after:\n', a) + +.. parsed-literal:: + + Gnerator() at 0x7f299de05340 + 6.384615058863119e-11 + + array([[0.4348157846574171, 0.7906325931024071, 0.878697619856133], + [0.8738606263361598, 0.4946080034142021, 0.7765890156101152], + [0.1770783715717074, 0.02080447648492112, 0.1053837559005948]], dtype=float64) + + buffer array before: + array([[0.0, 1.0, 2.0], + [3.0, 4.0, 5.0], + [6.0, 7.0, 8.0]], dtype=float64) + + buffer array after: + array([[0.8508024287393201, 0.9848489829156055, 0.7598167589604003], + [0.782995698302952, 0.2866337782847831, 0.7915884498022229], + [0.4614071706315902, 0.4792657443088592, 0.1581582066230718]], dtype=float64) + + + + +uniform +------- + +``uniform`` is similar to ``random``, except that the interval over +which the numbers are distributed can be specified, while the ``out`` +argument cannot. In addition to ``size`` specifying the shape of the +output, ``low=0.0``, and ``high=1.0`` are accepted arguments. With the +indicated defaults, ``uniform`` is identical to ``random``, which can be +seen from the fact that the first 3-by-3 tensor below is the same as the +one produced by ``rng.random(size=(3,3))`` above. + +If ``size`` is ``None``, a single floating point number will be +returned. + +``numpy``: +https://numpy.org/doc/stable/reference/random/generated/numpy.random.Generator.uniform.html + +.. code:: + + # code to be run in micropython + + from ulab import numpy as np + + rng = np.random.Generator(123456) + print(rng) + + print(rng.uniform()) + # returning numbers between 0, and 1 + print('\n', rng.uniform(size=(3,3))) + + # returning numbers between 10, and 20 + print('\n', rng.uniform(low=10, high=20, size=(3,3))) + + # same as above, without the keywords + print('\n', rng.uniform(10, 20, (3,3))) + +.. parsed-literal:: + + Gnerator() at 0x7f1891205340 + 6.384615058863119e-11 + + array([[0.4348157846574171, 0.7906325931024071, 0.878697619856133], + [0.8738606263361598, 0.4946080034142021, 0.7765890156101152], + [0.1770783715717074, 0.02080447648492112, 0.1053837559005948]], dtype=float64) + + array([[18.5080242873932, 19.84848982915605, 17.598167589604], + [17.82995698302952, 12.86633778284783, 17.91588449802223], + [14.6140717063159, 14.79265744308859, 11.58158206623072]], dtype=float64) + + array([[14.3380400319162, 12.72487657409978, 15.77119643621117], + [13.61835831436355, 18.96062889255558, 15.78847796795966], + [12.59435855187034, 17.68262037443622, 14.77943040598734]], dtype=float64) + + +