Rate this Page
★ ★ ★ ★ ★

torch.func._random.key#

torch.func._random.key(seed, *, device=None, impl='philox4x32-10')[source]#

Create a PRNG key from a seed.

A key is a tensor that encodes the state needed to deterministically produce random values. Keys are consumed by generation functions to produce reproducible random tensors without any global state. The internal representation of the key depends on the chosen PRNG algorithm.

Parameters:
  • seed (int) – The seed value for the PRNG.

  • device (torch.device, optional) – The desired device for the returned key. Default: the current default device (see torch.set_default_device()).

  • impl (str) – PRNG algorithm. Currently only "philox4x32-10" is supported.

Returns:

A tensor representing the PRNG key.

Return type:

Tensor

Note

For the "philox4x32-10" algorithm, the key is a uint64 tensor of shape (2,) encoding a (seed, offset) pair. The offset determines the starting position in the Philox output stream.

Each Philox call on a (seed, offset) pair produces 128 random bits, which yield E = 4 values for dtypes of 32 bits or fewer, or E = 2 for 64-bit dtypes. Each value of uniform(), randint(), and bits() comes from its own 128 / E bits, while normal() derives each pair of values from each pair’s worth of bits via the Box-Muller transform. Element i (in row-major order) of a key’s output, or of each slice a batched key generates, is value i % E of the call at (offset + i // E) % 2**64. Thus the key torch.tensor([seed, offset + k], dtype=torch.uint64) skips the first k * E elements, generating a contiguous range of the output starting there (e.g. a row shard of a parameter) directly. Such keys share counters with split() and fold_in() children of the original key, so don’t both shift and derive from the same key.

Example:

>>> key = torch.func._random.key(42, device="cuda")