randomgen.generator.Generator.integers

Generator.integers(low, high=None, size=None, dtype='int64', use_masked=True, endpoint=False)

Return random integers from low (inclusive) to high (exclusive), or if endpoint=True, low (inclusive) to high (inclusive).

Return random integers from the “discrete uniform” distribution of the specified dtype in the “half-open” interval [low, high). If high is None (the default), then results are from [0, low). If endpoint is True, then samples from the closed interval [low, high] or [0, low] if high is None.

Parameters

low{int, array_like[int]}

Lowest (signed) integers to be drawn from the distribution (unless high=None, in which case this parameter is one above the highest such integer).

high{int, array_like[int]}, 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

sizeint 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{str, dtype}, optional

Desired dtype of the result. All dtypes are determined by their name, i.e., ‘int64’, ‘int’, etc, so byteorder is not available and a specific precision may have different C types depending on the platform. The default value is ‘int’.

New in version 1.11.0.

use_maskedbool

If True the generator uses rejection sampling with a bit mask to reject random numbers that are out of bounds. If False the generator will use Lemire’s rejection sampling algorithm.

New in version 1.15.1.

endpointbool

If true, sample from the interval [low, high] instead of the default [low, high)

Returns

outint 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

1

Daniel Lemire., “Fast Random Integer Generation in an Interval”, CoRR, Aug. 13, 2018, https://arxiv.org/abs/1805.10941

Examples

>>> randomgen.generator.integers(2, size=10)
array([1, 0, 0, 0, 1, 1, 0, 0, 1, 0])  # random
>>> randomgen.generator.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:

>>> randomgen.generator.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

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

Generate a 1 by 3 array with 3 different lower bounds

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

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

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