# 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:

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.

```# 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)))
```
```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.

```# 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)
```
```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.

```# 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)))
```
```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)
```