Random

Collection of random Ivy functions.

ivy.multinomial(population_size, num_samples, /, *, batch_size=1, probs=None, replace=True, device=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)

  • 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

<module ‘ivy.array’ from ‘/home/root/project/ivy/array/__init__.py’>

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, 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

  • 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, 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

  • 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

<module ‘ivy.array’ from ‘/home/root/project/ivy/array/__init__.py’>

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, 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

  • 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, /, *, out=None)[source]

Shuffles the given array along axis 0.

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

  • 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

>>> x = ivy.array([1, 2, 3, 4, 5])
>>> y = ivy.shuffle(x)
>>> print(y)
ivy.array([2, 1, 4, 3, 5])