flopscope.numpy.random.Generator.integers

fnp.random.Generator.integers(self, low, high=None, size=None, dtype=<class 'numpy.int64'>, endpoint=False)

Return random integers from `low` (inclusive) to `high` (exclusive), or if endpoint=True, `low` (inclusive) to `high` (inclusive). Replaces `RandomState.randint` (with endpoint=False) and `RandomState.random_integers` (with endpoint=True)

Adapted from NumPy docs np.random.Generator.integers

Arearandom

Typecounted

NumPy Refnp.random.Generator.integers

Cost

\text{numel}(\text{output})

Flopscope Context

Modern Generator integers (replaces legacy randint).

Return random integers from low (inclusive) to high (exclusive), or if endpoint=True, low (inclusive) to high (inclusive). Replaces RandomState.randint (with endpoint=False) and RandomState.random_integers (with endpoint=True)

Return random integers from the "discrete uniform" distribution of the specified dtype. If high is None (the default), then results are from 0 to low.

Parameters

low:int or array-like of ints: Lowest (signed) integers to be drawn from the distribution (unless high=None, in which case this parameter is 0 and this value is used for high).
high:int or array-like of ints, optional: If provided, one above the largest (signed) integer to be drawn from the distribution (see above for behavior if high=None). If array-like, must contain integer values
size:int or tuple of ints, optional: Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
dtype:dtype, optional: Desired dtype of the result. Byteorder must be native. The default value is flops.int64.
endpoint:bool, optional: If true, sample from the interval [low, high] instead of the default [low, high) Defaults to False

Returns

out:int or ndarray of ints: size-shaped array of random integers from the appropriate distribution, or a single such random int if size not provided.

Notes

When using broadcasting with uint64 dtypes, the maximum value (2**64) cannot be represented as a standard integer type. The high array (or low if high is None) must have object dtype, e.g., array([2**64]).

References

footnote

1

Daniel Lemire., "Fast Random Integer Generation in an Interval",
ACM Transactions on Modeling and Computer Simulation 29 (1), 2019,
https://arxiv.org/abs/1805.10941.

Examples

>>> rng = flops.random.default_rng()
>>> rng.integers(2, size=10)
array([1, 0, 0, 0, 1, 1, 0, 0, 1, 0])  # random
>>> rng.integers(1, size=10)
array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0])

Generate a 2 x 4 array of ints between 0 and 4, inclusive:

>>> rng.integers(5, size=(2, 4))
array([[4, 0, 2, 1],
       [3, 2, 2, 0]])  # random

Generate a 1 x 3 array with 3 different upper bounds

>>> rng.integers(1, [3, 5, 10])
array([2, 2, 9])  # random

Generate a 1 by 3 array with 3 different lower bounds

>>> rng.integers([1, 5, 7], 10)
array([9, 8, 7])  # random

Generate a 2 by 4 array using broadcasting with dtype of uint8

>>> rng.integers([1, 3, 5, 7], [[10], [20]], dtype=flops.uint8)
array([[ 8,  6,  9,  7],
       [ 1, 16,  9, 12]], dtype=uint8)  # random