`heat.random`

Provides parallel random number generators (pRNG)

Module Contents

get_state() → Tuple[str, int, int, int, float]

Return a tuple representing the internal state of the generator. The returned tuple has the following items:

The string ‘Threefry’,
The Threefry key value, aka seed,
The internal counter value,
An integer has_gauss, always set to 0 (present for compatibility with numpy) and
A float cached_gaussian, always set to 0.0 (present for compatibility with numpy).

normal(mean: float | heat.core.dndarray.DNDarray = 0.0, std: float | heat.core.dndarray.DNDarray = 1.0, shape: Tuple[int, Ellipsis] | None = None, dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: str | None = None, comm: heat.core.communication.Communication | None = None) → heat.core.dndarray.DNDarray

Returns an array filled with random numbers from a normal distribution whose mean and standard deviation are given. If std and mean are DNDarrays, they have to match shape.

Parameters:

mean (float or DNDarray) – The mean of the distribution.
std (float or DNDarray) – The standard deviation of the distribution. Must be non-negative.
shape (tuple[int]) – The shape of the returned array, should all be positive. If no argument is given a single random sample is generated.
dtype (Type[datatype], optional) – The datatype of the returned values. Has to be one of float32 or float64.
split (int, optional) – The axis along which the array is split and distributed, defaults to no distribution.
device (str, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.

See also

randn: Uses the standard normal distribution
standard_noramal: Uses the standard normal distribution

Examples

>>> ht.random.normal(ht.array([-1,2]), ht.array([0.5, 2]), (2,))
DNDarray([-1.4669,  1.6596], dtype=ht.float64, device=cpu:0, split=None)

permutation(x: int | heat.core.dndarray.DNDarray) → heat.core.dndarray.DNDarray

Randomly permute a sequence, or return a permuted range. If x is a multi-dimensional array, it is only shuffled along its first index.

Parameters:: x (int or DNDarray) – If x is an integer, call heat.random.randperm. If x is an array, make a copy and shuffle the elements randomly.

See also

heat.random.randperm for randomly permuted ranges.

Examples

>>> ht.random.permutation(10)
DNDarray([9, 1, 5, 4, 8, 2, 7, 6, 3, 0], dtype=ht.int64, device=cpu:0, split=None)
>>> ht.random.permutation(ht.array([1, 4, 9, 12, 15]))
DNDarray([ 9,  1, 12,  4, 15], dtype=ht.int64, device=cpu:0, split=None)
>>> arr = ht.arange(9).reshape((3, 3))
>>> ht.random.permutation(arr)
DNDarray([[3, 4, 5],
          [6, 7, 8],
          [0, 1, 2]], dtype=ht.int32, device=cpu:0, split=None)

rand(*args: List[int], dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: heat.core.devices.Device | None = None, comm: heat.core.communication.Communication | None = None) → heat.core.dndarray.DNDarray

Random values in a given shape. Create a DNDarray of the given shape and populate it with random samples from a uniform distribution over \([0, 1)\).

Parameters:

d1 (List[int,...]) – The dimensions of the returned array, should all be positive. If no argument is given a single random samples is generated.
d2 (List[int,...]) – The dimensions of the returned array, should all be positive. If no argument is given a single random samples is generated.
… (List[int,...]) – The dimensions of the returned array, should all be positive. If no argument is given a single random samples is generated.
dn (List[int,...]) – The dimensions of the returned array, should all be positive. If no argument is given a single random samples is generated.
dtype (Type[datatype], optional) – The datatype of the returned values. Has to be one of float32 or float64.
split (int, optional) – The axis along which the array is split and distributed, defaults to no distribution.
device (str, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.

Raises:

ValueError – If there are negative or not-integer convertible dimensions given or if the passed dtype was non-floating point.

Examples

>>> ht.rand(3)
DNDarray([0.1921, 0.9635, 0.5047], dtype=ht.float32, device=cpu:0, split=None)

Random values in a given shape. Create a tensor of the given shape and populate it with random integer samples from a uniform distribution over \([low, high)\) or \([0, low)\) if high is not provided.

Parameters:

low (int) – Lowest (signed) integer to be drawn from the distribution (unless high=None, in which case this parameter is one above the highest such integer).
high (int, optional) – If provided, one above the largest (signed) integer to be drawn from the distribution (see above for behavior if high=None).
size (int or Tuple[int,...], optional) – Output shape. If the given shape is, e.g., \((m, n, k)\), then \(m \times n \times k\) samples are drawn. Default is None, in which case a single value is returned.
dtype (datatype, optional) – Desired datatype of the result. Must be an integer type, defaults to int32.
split (int, optional) – The axis along which the array is split and distributed, defaults to no distribution.
device (str, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.

Raises:

TypeError – If one of low or high is not an int.
ValueError – If low >= high, dimensions are negative or the passed datatype is not an integer.

Examples

>>> ht.randint(3)
DNDarray([4, 101, 16], dtype=ht.int32, device=cpu:0, split=None)

random_integer(low: int, high: int | None = None, size: int | Tuple[int] | None = None, dtype: Type[heat.core.types.datatype] | None = types.int32, split: int | None = None, device: str | None = None, comm: heat.core.communication.Communication | None = None) → heat.core.dndarray.DNDarray: Alias for heat.random.randint.

randn(*args: List[int], dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: str | None = None, comm: heat.core.communication.Communication | None = None) → heat.core.dndarray.DNDarray

Returns a tensor filled with random numbers from a standard normal distribution with zero mean and variance of one.

Parameters:

d1 (List[int,...]) – The dimensions of the returned array, should be all positive.
d2 (List[int,...]) – The dimensions of the returned array, should be all positive.
… (List[int,...]) – The dimensions of the returned array, should be all positive.
dn (List[int,...]) – The dimensions of the returned array, should be all positive.
dtype (Type[datatype], optional) – The datatype of the returned values. Has to be one of float32 or float64.
split (int, optional) – The axis along which the array is split and distributed, defaults to no distribution.
device (str, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.

See also

normal: Similar, but takes a tuple as its argumant.
standard_normal: Accepts arguments for mean and standard deviation.

Raises:

TypeError – If one of d1 to dn is not an integer.
ValueError – If one of d1 to dn is less or equal to 0.

Examples

>>> ht.randn(3)
DNDarray([ 0.1921, -0.9635,  0.5047], dtype=ht.float32, device=cpu:0, split=None)
>>> ht.randn(4, 4)
DNDarray([[-1.1261,  0.5971,  0.2851,  0.9998],
          [-1.8548, -1.2574,  0.2391, -0.3302],
          [ 1.3365, -1.5212,  1.4159, -0.1671],
          [ 0.1260,  1.2126, -0.0804,  0.0907]], dtype=ht.float32, device=cpu:0, split=None)

randperm(n: int, dtype: Type[heat.core.types.datatype] = types.int64, split: int | None = None, device: str | None = None, comm: heat.core.communication.Communication | None = None) → heat.core.dndarray.DNDarray

Returns a random permutation of integers from \(0\) to \(n - 1\).

Parameters:

n (int) – Upper, exclusive bound for the integer range.
dtype (datatype, optional) – The datatype of the returned values.
split (int, optional) – The axis along which the array is split and distributed, defaults to no distribution.
device (str, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.

Raises:

TypeError – If n is not an integer.

Examples

>>> ht.random.randperm(4)
DNDarray([2, 3, 1, 0], dtype=ht.int64, device=cpu:0, split=None)

random(shape: Tuple[int] | None = None, dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: str | None = None, comm: heat.core.communication.Communication | None = None)

Populates a DNDarray of the given shape with random samples from a continuous uniform distribution over \([0.0, 1.0)\).

Parameters:

shape (tuple[int]) – The shape of the returned array, should all be positive. If no argument is given a single random sample is generated.
dtype (Type[datatype], optional) – The datatype of the returned values. Has to be one of float32 or float64.
split (int, optional) – The axis along which the array is split and distributed, defaults to no distribution.
device (str, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.

Examples

>>> ht.random.random_sample()
0.47108547995356098
>>> ht.random.random_sample((3,))
DNDarray([0.30220482, 0.86820401, 0.1654503], dtype=ht.float32, device=cpu:0, split=None)

ranf(shape: Tuple[int] | None = None, dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: str | None = None, comm: heat.core.communication.Communication | None = None): Alias for heat.random.random.

random_sample(shape: Tuple[int] | None = None, dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: str | None = None, comm: heat.core.communication.Communication | None = None): Alias for heat.random.random.

sample(shape: Tuple[int] | None = None, dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: str | None = None, comm: heat.core.communication.Communication | None = None): Alias for heat.random.random.

seed(seed: int | None = None)

Seed the generator.

Parameters:: seed (int, optional) – Value to seed the algorithm with, if not set a time-based seed is generated.

set_state(state: Tuple[str, int, int, int, float])

Set the internal state of the generator from a tuple. The tuple has the following items:

The string ‘Threefry’,
The Threefry key value, aka seed,
The internal counter value,
An integer has_gauss, ignored (present for compatibility with numpy), optional and
A float cached_gaussian, ignored (present for compatibility with numpy), optional.

Parameters:

state (Tuple[str, int, int, int, float]) – Sets the state of the random generator to the passed values. Allows to select seed and counter values manually.

Raises:

TypeError – If and improper state is passed.
ValueError – If one of the items in the state tuple is of wrong type or value.

standard_normal(shape: Tuple[int, Ellipsis] | None = None, dtype: Type[heat.core.types.datatype] = types.float32, split: int | None = None, device: str | None = None, comm: heat.core.communication.Communication | None = None) → heat.core.dndarray.DNDarray

Returns an array filled with random numbers from a standard normal distribution with zero mean and variance of one.

Parameters:

shape (tuple[int]) – The shape of the returned array, should all be positive. If no argument is given a single random sample is generated.
dtype (Type[datatype], optional) – The datatype of the returned values. Has to be one of float32 or float64.
split (int, optional) – The axis along which the array is split and distributed, defaults to no distribution.
device (str, optional) – Specifies the Device the array shall be allocated on, defaults to globally set default device.
comm (Communication, optional) – Handle to the nodes holding distributed parts or copies of this array.

See also

randn: Similar, but accepts separate arguments for the shape dimensions.
normal: Equivalent function with arguments for the mean and standard deviation.

Examples

>>> ht.random.standard_normal((3,))
DNDarray([ 0.1921, -0.9635,  0.5047], dtype=ht.float32, device=cpu:0, split=None)
>>> ht.random.standard_normal((4, 4))
DNDarray([[-1.1261,  0.5971,  0.2851,  0.9998],
          [-1.8548, -1.2574,  0.2391, -0.3302],
          [ 1.3365, -1.5212,  1.4159, -0.1671],
          [ 0.1260,  1.2126, -0.0804,  0.0907]], dtype=ht.float32, device=cpu:0, split=None)

heat.random

Module Contents

`heat.random`