add random documentation rst file (#655)

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 <https://en.wikipedia.org/wiki/Box%E2%80%93Muller_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)
+    
+    
+