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 isTrue
. (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:
- 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
]]) – If the given shape is, e.g(m, n, k)
, thenm * n * k
samples are drawn (default:None
) Can only be specified whenmean
andstd
are numeric values, else exception will be raised. Default isNone
, 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. Ifdtype
isNone
, the output array data (default:None
) type will be the default integer data type. DefaultNone
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:
- 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
]) – The mean of the normal distribution to sample from. Default is0.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 is1.0
.shape (
Optional
[Union
[Shape
,NativeShape
]]) – If the given shape is, e.g(m, n, k)
, thenm * n * k
samples are drawn. (default:None
) Can only be specified whenmean
andstd
are numeric values, else exception will be raised. Default isNone
, where a single value is returned.dtype (
Optional
[Union
[Dtype
,NativeDtype
]]) – output array data type. Ifdtype
isNone
, the output array data (default:None
) type will be the default floating-point data type. DefaultNone
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:
- 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), 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)
(includeslow
, but excludeshigh
). 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 tolow
. If array, must have same shape ashigh
.high (
Union
[float
,NativeArray
,Array
]) – Upper boundary of the output interval. All the values generated will be less (default:1.0
) thanhigh
. If array, must have same shape aslow
.shape (
Optional
[Union
[Array
,Shape
,NativeShape
]]) – If the given shape is, e.g(m, n, k)
, thenm * n * k
samples are drawn. (default:None
) Can only be specified whenlow
andhigh
are numeric values, else exception will be raised. Default isNone
, 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. Ifdtype
isNone
, the output array data (default:None
) type will be the default floating-point data type. DefaultNone
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:
- 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, 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
) – 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, 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
]) – The axis which x is shuffled along. Default is 0. (default:0
)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:
- 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 or in the random forum!