# 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`, default: `1`) – Number of tensors to generate. Default is 1.

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

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

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

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

• out (`Optional`[`Array`], default: `None`) – optional output array, for writing the result to. It must have a shape that the 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, seed=42)
>>> print(y)
ivy.array([[3, 9, 7, 5, 1],
[1, 0, 8, 6, 7]])
```
```>>> 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]#

Return 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`]], default: `None`) – If the given shape is, e.g `(m, n, k)`, then `m * n * k` samples are drawn 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`]], default: `None`) – device on which to create the array. ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. (Default value = None).

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

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

• out (`Optional`[`Array`], default: `None`) – optional output array, for writing the result to. It must have a shape 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', seed=42)
>>> print(y)
ivy.array([[ 8, 16],
[12,  9]])
```
```>>> 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`], default: `0.0`) – The mean of the normal distribution to sample from. Default is `0.0`.

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

• shape (`Optional`[`Union`[`Shape`, `NativeShape`]], default: `None`) – If the given shape is, e.g `(m, n, k)`, then `m * n * k` samples are drawn. 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`]], default: `None`) – output array data type. If `dtype` is `None`, the output array data type will be the default floating-point data type. Default `None`

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

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

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

Return type:

`Array`

Returns:

ret

Drawn samples from the parameterized normal distribution.

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), seed=42)
ivy.array([[ 0.49671414, -0.1382643 ,  0.64768857],
[ 1.5230298 , -0.23415337, -0.23413695]])
```
```>>> 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`], default: `0.0`) – Lower boundary of the output interval. All values generated will be greater than or equal to `low`. If array, must have same shape as `high`.

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

• shape (`Optional`[`Union`[`Array`, `Shape`, `NativeShape`]], default: `None`) – If the given shape is, e.g `(m, n, k)`, then `m * n * k` samples are drawn. 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`]], default: `None`) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. (Default value = None).

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

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

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

Return type:

`Array`

Returns:

ret – Drawn samples from the parameterized uniform distribution.

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, seed=42)
ivy.array([6.67270088, 7.31128597])
```
```>>> 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]#

Set the seed for random number generation.

Parameters:

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

Return type:

`None`

Examples

```>>> ivy.seed(seed_value=42)
```
ivy.shuffle(x, axis=0, /, *, seed=None, out=None)[source]#

Shuffles the given array along a given axis.

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

• axis (`Optional`[`int`], default: `0`) – The axis which x is shuffled along. Default is 0.

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

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

Return type:

`Array`

Returns:

ret – An array object, shuffled along the specified axis.

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!