torch.func._random.randint#
- torch.func._random.randint(key, *shape, low=0, high=None, dtype=None)[source]#
Generate uniform random integers in
[low, high)from a PRNG key.Produces a tensor of the given shape filled with integers drawn uniformly from
[low, high). The output is fully determined by the key, so calling with the same key always returns the same result. The output is placed on the same device askey.lowdefaults to0andhighto the dtype’s largest value plus one. PassingNonefor either selects the corresponding limit ofdtype, solow=Nonewith nohighdraws from the full range.Warning
The signature differs from
torch.randint(). Bounds are keyword-only and follow the shape, matchinguniform()andnormal()in this module, whereastorch.randint()takes them positionally before the size:torch.randint(10, (2, 3)) # -> [0, 10) randint(key, (2, 3), high=10) torch.randint(1, 5, (2, 3)) # -> [1, 5) randint(key, (2, 3), low=1, high=5)
Note that a positional integer is a shape dimension here, not a bound, so
randint(key, 10, high=5)produces ten values in[0, 5)rather than the[0, 10)thattorch.randint()would give.This function also accepts
Nonebounds for the dtype’s limits, whichtorch.randint()does not.Supports batched keys: if
keyhas shape(*batch, K), the leading dimensions ofshapemust be broadcastable with*batchand each key independently generates its slice of the output.- Parameters:
key (Tensor) – A PRNG key returned by
key(),split(), orfold_in().*shape (int) – The desired output shape.
low (int, optional) – Lower bound (inclusive) of the range.
Nonemeans the dtype’s smallest value. Default:0.high (int, optional) – Upper bound (exclusive) of the range.
Nonemeans the dtype’s largest value plus one. For 32-bit dtypes,high - lowmust be a power of two or less than2 ** 28; see the note below. Default:None.dtype (
torch.dtype, optional) – The desired dtype: any integer dtype other thantorch.bool. Default:torch.int32.
- Returns:
A tensor of the given shape filled with random integers.
- Return type:
Note
Sampling width. Each element draws a fixed
nbitsof randomness: 64 for the 8-byte dtypes (torch.int64/torch.uint64) and 32 for every narrower one. Dtypes smaller than 32 bits are not packed several to a word; each element still consumes a full 32-bit sample, the range reduction is done at 32 bits, and only the final store narrows to the output dtype (keeping the low bits). Samplingtorch.int8therefore matches samplingtorch.int32and casting down withto(), and its bias is measured against2 ** 32rather than2 ** 8.Sampling bias. The
nbitssample is reduced into[low, high)with a modulo. That is exactly uniform only whenhigh - lowdivides2 ** nbits, i.e. when the range is a power of two; otherwise the lowest2 ** nbits % (high - low)values of the range are returned slightly more often than the rest.With
q = 2 ** nbits // (high - low), the most frequent value occurs1 + 1 / qtimes as often as the least frequent, so the worst case grows with the range:q = 2**nbits // (high - low) bias = 0.0 if 2**nbits % (high - low) == 0 else 1.0 / q
Away from the exact cases this is close to
(high - low) / 2 ** nbits. It is a step function of the range, changing only whereqdoes. Exact powers of two are unbiased, so the figures below bound every range up to the listed size, for a 32-bit dtype:Range up to
Max relative bias
2 ** 80.000006%
2 ** 160.0015%
2 ** 200.024%
2 ** 240.39%
2 ** 261.6%
2 ** 273.1%
2 ** 286.25%
Ranges of
2 ** 28or more are rejected for dtypes sampled at 32 bits, to keep the bias under roughly 6%; use a 64-bit dtype if you need a range that large. Ranges that divide2 ** 32evenly (powers of two) are exact at any size and are always allowed. Dtypes narrower than 32 bits can never reach that limit, since their ranges cap at2 ** 16, so their bias stays below 0.0015%. 64-bit dtypes are not restricted, since the same formula over2 ** 64keeps the bias near2e-10even at a range of2 ** 32.Using the dtype’s full range (omitting both bounds) is always exactly uniform, since that range is a power of two and no reduction is applied.
Example:
>>> r = torch.func._random >>> key = r.key(42, device="cuda") >>> r.randint(key, (1000,), high=10) # [0, 10) >>> r.randint(key, (1000,), low=-5, high=5) # [-5, 5) >>> r.randint(key, 2, 3, high=10, dtype=torch.int64) # shape (2, 3) >>> r.randint(key, (1000,), low=None) # the dtype's full range