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!