# Random

Collection of random Ivy functions.

ivy.multinomial(population_size, num_samples, /, *, batch_size=1, probs=None, replace=True, device=None, seed=None, out=None)[source]

Draws samples from a multinomial distribution. Specifically, returns a tensor where each row contains num_samples indices sampled from the multinomial probability distribution located in the corresponding row of tensor input.

Parameters
• population_size (`int`) – The size of the population from which to draw samples.

• num_samples (`int`) – Number of independent samples to draw from the population.

• batch_size (`int`) – Number of tensors to generate. Default is 1. (default: `1`)

• probs (`Optional`[`Union`[`Array`, `NativeArray`]]) – The unnormalized probabilities for all elements in population, (default: `None`) default is uniform [batch_shape, population_size]

• replace (`bool`) – Whether to replace samples once they’ve been drawn. Default is `True`. (default: `True`)

• device (`Optional`[`Union`[`Device`, `NativeDevice`]]) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. (default: `None`) (Default value = None)

• seed (`Optional`[`int`]) – A python integer. Used to create a random seed distribution (default: `None`)

• out (`Optional`[`Array`]) – optional output array, for writing the result to. It must have a shape that the (default: `None`) inputs broadcast to.

Return type

`Array`

Returns

ret – Drawn samples indices from the multinomial distribution.

Examples

```>>> y = ivy.multinomial(10, 5)
>>> print(y)
ivy.array([[1, 8, 7, 8, 3]])
```
```>>> y = ivy.multinomial(10, 5, batch_size=2)
>>> print(y)
ivy.array([[9, 7, 9, 0, 7],
[7, 3, 8, 5, 4]])
```
```>>> y = ivy.multinomial(10, 5, replace=False)
>>> print(y)
ivy.array([[2, 6, 4, 7, 0]])
```

With `ivy.Array` input:

```>>> y = ivy.multinomial(10, 5, probs=ivy.array([1/10]*10))
>>> print(y)
ivy.array([5, 2, 7, 6, 9])
```
```>>> y = ivy.multinomial(7, 5, batch_size=2, probs=ivy.array([[1/7]*7, [1/7]*7]))
>>> print(y)
ivy.array([[0, 4, 3, 4, 5], [1, 1, 0, 3, 2]])
```
```>>> y = ivy.multinomial(7, 5, batch_size=2, probs=ivy.array([[1/7]*7, [1/7]*7]),
...                     replace=False)
>>> print(y)
ivy.array([[2, 6, 1, 0, 3], [1, 0, 2, 5, 6]])
```

With `ivy.NativeArray` input:

```>>> y = ivy.multinomial(10, 5, probs=ivy.native_array([1/10]*10))
>>> print(y)
ivy.array([5, 7, 4, 2, 1])
```
```>>> y = ivy.multinomial(10, 5, batch_size=2,
...                     probs=ivy.native_array([[1/10]*10, [1/10]*10]))
>>> print(y)
ivy.array([[8, 0, 4, 1, 7], [2, 3, 4, 9, 3]])
```
```>>> y = ivy.multinomial(10, 5, batch_size=2,
...                     probs=ivy.native_array([[1/10]*10, [1/10]*10]),
...                     replace=False)
>>> print(y)
ivy.array([[0, 2, 6, 9, 1], [6, 7, 2, 4, 3]])
```
ivy.randint(low, high, /, *, shape=None, device=None, dtype=None, seed=None, out=None)[source]

Returns an array filled with random integers generated uniformly between low (inclusive) and high (exclusive).

Parameters
• low (`Union`[`int`, `NativeArray`, `Array`]) – Lowest integer that can be drawn from the distribution.

• high (`Union`[`int`, `NativeArray`, `Array`]) – One above the highest integer that can be drawn from the distribution.

• shape (`Optional`[`Union`[`Shape`, `NativeShape`]]) – If the given shape is, e.g `(m, n, k)`, then `m * n * k` samples are drawn (default: `None`) Can only be specified when `mean` and `std` are numeric values, else exception will be raised. Default is `None`, where a single value is returned.

• device (`Optional`[`Union`[`Device`, `NativeDevice`]]) – device on which to create the array. ‘cuda:0’, (default: `None`) ‘cuda:1’, ‘cpu’ etc. (Default value = None).

• dtype (`Optional`[`Union`[`Dtype`, `NativeDtype`]]) – output array data type. If `dtype` is `None`, the output array data (default: `None`) type will be the default integer data type. Default `None`

• seed (`Optional`[`int`]) – A python integer. Used to create a random seed distribution (default: `None`)

• out (`Optional`[`Array`]) – optional output array, for writing the result to. It must have a shape (default: `None`) that the inputs broadcast to.

Return type

`Array`

Returns

ret – Returns an array with the given shape filled with integers from the uniform distribution in the “half-open” interval [low, high)

Examples

```>>> y = ivy.randint(0, 9, shape=(1,1))
>>> print(y)
ivy.array([[5]])
```
```>>> y = ivy.randint(2, 20, shape=(2, 2), device='cpu')
>>> print(y)
ivy.array([[5,8],[9,3]])
```
```>>> x = ivy.array([1, 2, 3])
>>> ivy.randint(0, 10, shape=(3,), out=x)
>>> print(x)
ivy.array([2, 6, 7])
```
```>>> y = ivy.zeros((3, 3))
>>> ivy.randint(3, 15, shape=(3, 3), device='cpu', out=y)
>>> print(y)
ivy.array([[ 7,  7,  5],
[12,  8,  8],
[ 8, 11,  3]])
```
ivy.random_normal(*, mean=0.0, std=1.0, shape=None, dtype=None, seed=None, device=None, out=None)[source]

Draws samples from a normal distribution.

Parameters
• mean (`Union`[`float`, `NativeArray`, `Array`]) – The mean of the normal distribution to sample from. Default is `0.0`. (default: `0.0`)

• std (`Union`[`float`, `NativeArray`, `Array`]) – The standard deviation of the normal distribution to sample from. (default: `1.0`) Must be non-negative. Default is `1.0`.

• shape (`Optional`[`Union`[`Shape`, `NativeShape`]]) – If the given shape is, e.g `(m, n, k)`, then `m * n * k` samples are drawn. (default: `None`) Can only be specified when `mean` and `std` are numeric values, else exception will be raised. Default is `None`, where a single value is returned.

• dtype (`Optional`[`Union`[`Dtype`, `NativeDtype`]]) – output array data type. If `dtype` is `None`, the output array data (default: `None`) type will be the default floating-point data type. Default `None`

• seed (`Optional`[`int`]) – A python integer. Used to create a random seed distribution (default: `None`)

• device (`Optional`[`Union`[`Device`, `NativeDevice`]]) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. (default: `None`) (Default value = None).

• out (`Optional`[`Array`]) – optional output array, for writing the result to. It must have a shape that the (default: `None`) inputs broadcast to.

Return type

`Array`

Returns

ret – Drawn samples from the parameterized normal distribution.

Functional Examples

```>>> ivy.random_normal()
ivy.array(-0.22346112)
```
```>>> ivy.random_normal(shape=3)
ivy.array([-0.73  ,  0.0922, -0.515 ])
```
```>>> ivy.random_normal(shape=(2,3))
ivy.array([[-0.361 ,  0.596 , -0.247 ],
[-1.39  ,  0.0426, -0.627 ]])
```
```>>> ivy.random_normal(mean=3.0, std=6.0)
ivy.array(4.9213753)
```
```>>> ivy.random_normal(mean=1.0, std=2.0, shape=(2,1))
ivy.array([[2.19],
[2.78]])
```
```>>> z = ivy.zeros(())
>>> ivy.random_normal(mean=1.0, std=2.0, out=z)
ivy.array(0.12818667)
```
```>>> ivy.random_normal(mean=1.0, std=2.0, shape=(2,2), device='cpu')
ivy.array([[ 2.91 ,  1.3  ],
[ 3.37 , -0.799]])
```
```>>> ivy.random_normal(mean=1.0, std=2.0, shape=(2,2), device='cpu',
...                   dtype='int32')
ivy.array([[ 0, -1],
[ 0,  3]])
```
```>>> z = ivy.zeros((1,2))
>>> ivy.random_normal(mean=1.0, std=2.0, shape=(1,2), device='cpu',
...                   dtype='float64', out=z)
ivy.array([[-2.01, -1.95]])
```
```>>> x = ivy.array([4.8, 5.6])
>>> y = ivy.array([9.8, 7.4])
>>> ivy.random_normal(mean=x, std=y)
ivy.array([ 4.43 , -0.469])
```
```>>> z = ivy.zeros((2,))
>>> ivy.random_normal(mean=x, std=y, out=z)
ivy.array([0.287, 8.55 ])
```
```>>> ivy.random_normal(mean=x, std=y, device='cpu')
ivy.array([18.9, 15.2])
```
```>>> ivy.random_normal(mean=x, std=y, device='cpu', dtype='float64')
ivy.array([-4.1   , -0.0366])
```
```>>> z = ivy.zeros((2,))
>>> ivy.random_normal(mean=x, std=y, device='cpu', dtype='float64', out=z)
ivy.array([12.4, 11. ])
```
ivy.random_uniform(*, low=0.0, high=1.0, shape=None, device=None, dtype=None, seed=None, out=None)[source]

Draws samples from a uniform distribution. Samples are uniformly distributed over the half-open interval `[low, high)` (includes `low`, but excludes `high`). In other words, any value within the given interval is equally likely to be drawn by uniform.

Parameters
• low (`Union`[`float`, `NativeArray`, `Array`]) – Lower boundary of the output interval. All values generated will be greater than (default: `0.0`) or equal to `low`. If array, must have same shape as `high`.

• high (`Union`[`float`, `NativeArray`, `Array`]) – Upper boundary of the output interval. All the values generated will be less (default: `1.0`) than `high`. If array, must have same shape as `low`.

• shape (`Optional`[`Union`[`Shape`, `NativeShape`]]) – If the given shape is, e.g `(m, n, k)`, then `m * n * k` samples are drawn. (default: `None`) Can only be specified when `low` and `high` are numeric values, else exception will be raised. Default is `None`, where a single value is returned.

• device (`Optional`[`Union`[`Device`, `NativeDevice`]]) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. (default: `None`) (Default value = None).

• dtype (`Optional`[`Union`[`Dtype`, `NativeDtype`]]) – output array data type. If `dtype` is `None`, the output array data (default: `None`) type will be the default floating-point data type. Default `None`

• seed (`Optional`[`int`]) – A python integer. Used to create a random seed distribution (default: `None`)

• out (`Optional`[`Array`]) – optional output array, for writing the result to. It must have a shape that the (default: `None`) inputs broadcast to.

Return type

`Array`

Returns

ret – Drawn samples from the parameterized uniform distribution.

Functional Examples

```>>> ivy.random_uniform()
ivy.array(0.26431865)
```
```>>> ivy.random_uniform(shape=3)
ivy.array([0.475, 0.878, 0.861])
```
```>>> ivy.random_uniform(shape=(2,3))
ivy.array([[0.929 , 0.545 , 0.789 ],
[0.519 , 0.0435, 0.381 ]])
```
```>>> ivy.random_uniform(low=3.0, high=6.0)
ivy.array(3.4608004)
```
```>>> ivy.random_uniform(low=1.0, high=2.0, shape=(2,1))
ivy.array([[1.85],
[1.81]])
```
```>>> z = ivy.zeros(())
>>> ivy.random_uniform(low=1.0, high=2.0, out=z)
ivy.array(1.8458502)
```
```>>> ivy.random_uniform(low=1.0, high=2.0, shape=(2,2), device='cpu')
ivy.array([[1.81, 1.8 ],
[1.32, 1.43]])
```
```>>> ivy.random_uniform(low=1.0, high=2.0, shape=(2,2), device='cpu',
...                    dtype='int32')
ivy.array([[1, 1],
[1, 1]])
```
```>>> z = ivy.zeros((1,2))
>>> ivy.random_uniform(low=1.0, high=2.0, shape=(1,2), device='cpu',
...                    dtype='float64', out=z)
ivy.array([[1.34, 1.02]])
```
```>>> x = ivy.array([4.8, 5.6])
>>> y = ivy.array([9.8, 7.4])
>>> ivy.random_uniform(low=x, high=y)
ivy.array([0.475, 0.878])
```
```>>> z = ivy.zeros((2,))
>>> ivy.random_uniform(low=x, high=y, out=z)
ivy.array([9.41, 7.17])
```
```>>> ivy.random_uniform(low=x, high=y, device='cpu')
ivy.array([6.88, 6.75])
```
```>>> ivy.random_uniform(low=x, high=y, device='cpu', dtype='float64')
ivy.array([8.62, 6.47])
```
```>>> z = ivy.zeros((2,))
>>> ivy.random_uniform(low=x, high=y, device='cpu', dtype='float64', out=z)
ivy.array([5. , 7.3])
```
ivy.seed(*, seed_value=0)[source]

Sets the seed for random number generation.

Parameters

seed_value (`int`) – Seed for random number generation, must be a positive integer. (default: `0`) (Default value = 0)

Examples

```>>> ivy.seed(seed_value=42)
```
Return type

`None`

ivy.shuffle(x, /, *, seed=None, out=None)[source]

Shuffles the given array along axis 0.

Parameters
• x (`Union`[`Array`, `NativeArray`]) – Input array. Should have a numeric data type.

• seed (`Optional`[`int`]) – A python integer. Used to create a random seed distribution (default: `None`)

• out (`Optional`[`Array`]) – optional output array, for writing the result to. It must have a shape that the (default: `None`) inputs broadcast to.

Return type

`Array`

Returns

ret – An array object, shuffled along the first dimension.

Examples

With `ivy.Array` input:

```>>> x = ivy.array([1, 2, 3, 4, 5])
>>> y = ivy.shuffle(x)
>>> print(y)
ivy.array([2, 1, 4, 3, 5])
```
```>>> x = ivy.array([1, 3, 5, 7])
>>> y = ivy.shuffle(x, seed=394)
>>> print(y)
ivy.array([3, 1, 5, 7])
```
```>>> x = ivy.array([1, 0, 5])
>>> y = ivy.array([0, 0, 0])
>>> ivy.shuffle(x, seed=394, out=y)
>>> print(y)
ivy.array([0, 1, 5])
```

With `ivy.Container` input:

```>>> x = ivy.Container(a=ivy.array([5, 2, 9]),
...                   b=ivy.array([7, 1, 6]))
>>> y = ivy.shuffle(x)
>>> print(y)
{
a: ivy.array([5, 9, 2]),
b: ivy.array([6, 1, 7])
}
```
```>>> x = ivy.Container(a=ivy.array([7, 4, 5]),
...                   b=ivy.array([9, 8, 2]))
>>> y = ivy.Container(a=ivy.array([0, 0, 0]),
...                   b=ivy.array([0, 0, 0]))
>>> ivy.shuffle(x, seed=17, out=y)
>>> print(y)
{
a: ivy.array([7, 5, 4]),
b: ivy.array([9, 2, 8])
}
```
```>>> x = ivy.Container(a=ivy.array([8, 2, 5]),
...                   b=ivy.array([3, 9, 0]))
>>> ivy.shuffle(x, seed=17, out=x)
>>> print(x)
{
a: ivy.array([2, 8, 5]),
b: ivy.array([3, 0, 9])
}
```

This should have hopefully given you an overview of the random submodule,If you have any questions, please feel free to reach out on our discord in the random channel or in the random forum!