tf.random.experimental.Generator

TensorFlow 1 version View source on GitHub

Random-number generator.

tf.random.experimental.Generator(
    copy_from=None, state=None, alg=None
)

It uses Variable to manage its internal state, and allows choosing an Random-Number-Generation (RNG) algorithm.

CPU, GPU and TPU with the same algorithm and seed will generate the same integer random numbers. Float-point results (such as the output of normal) may have small numerical discrepancies between CPU and GPU.

Args:

  • copy_from: a generator to be copied from.
  • state: a vector of dtype STATE_TYPE representing the initial state of the RNG, whose length and semantics are algorithm-specific.
  • alg: the RNG algorithm. Possible values are RNG_ALG_PHILOX for the Philox algorithm and RNG_ALG_THREEFRY for the ThreeFry algorithm (see paper 'Parallel Random Numbers: As Easy as 1, 2, 3' [https://www.thesalmons.org/john/random123/papers/random123sc11.pdf]). Note RNG_ALG_PHILOX guarantees the same numbers are produced (given the same random state) across all architextures (CPU, GPU, XLA etc).

Attributes:

  • algorithm: The RNG algorithm.
  • key: The 'key' part of the state of a counter-based RNG.

    For a counter-base RNG algorithm such as Philox and ThreeFry (as described in paper 'Parallel Random Numbers: As Easy as 1, 2, 3' [https://www.thesalmons.org/john/random123/papers/random123sc11.pdf]), the RNG state consists of two parts: counter and key. The output is generated via the formula: output=hash(key, counter), i.e. a hashing of the counter parametrized by the key. Two RNGs with two different keys can be thought as generating two independent random-number streams (a stream is formed by increasing the counter).

  • state: The internal state of the RNG.

Methods

binomial

View source

binomial(
    shape, counts, probs, dtype=tf.dtypes.int32, name=None
)

Outputs random values from a binomial distribution.

The generated values follow a binomial distribution with specified count and probability of success parameters.

Example:

counts = [10., 20.]
# Probability of success.
probs = [0.8, 0.9]

rng = tf.random.experimental.Generator.from_seed(seed=234)
binomial_samples = rng.binomial(shape=[2], counts=counts, probs=probs)

Args:

  • shape: A 1-D integer Tensor or Python array. The shape of the output tensor.
  • counts: A 0/1-D Tensor or Python value. The counts of the binomial distribution. Must be broadcastable with the leftmost dimension defined by shape.
  • probs: A 0/1-D Tensor or Python value. The probability of success for the binomial distribution. Must be broadcastable with the leftmost dimension defined by shape.
  • dtype: The type of the output. Default: tf.int32
  • name: A name for the operation (optional).

Returns:

  • samples: A Tensor of the specified shape filled with random binomial values. For each i, each samples[i, ...] is an independent draw from the binomial distribution on counts[i] trials with probability of success probs[i].

from_key_counter

View source

@classmethod
from_key_counter(
    key, counter, alg
)

Creates a generator from a key and a counter.

This constructor only applies if the algorithm is a counter-based algorithm. See method key for the meaning of "key" and "counter".

Args:

  • key: the key for the RNG, a scalar of type STATE_TYPE.
  • counter: a vector of dtype STATE_TYPE representing the initial counter for the RNG, whose length is algorithm-specific.,
  • alg: the RNG algorithm. If None, it will be auto-selected. See __init__ for its possible values.

Returns:

The new generator.

from_non_deterministic_state

View source

@classmethod
from_non_deterministic_state(
    alg=None
)

Creates a generator by non-deterministically initializing its state.

The source of the non-determinism will be platform- and time-dependent.

Args:

  • alg: (optional) the RNG algorithm. If None, it will be auto-selected. See __init__ for its possible values.

Returns:

The new generator.

from_seed

View source

@classmethod
from_seed(
    seed, alg=None
)

Creates a generator from a seed.

A seed is a 1024-bit unsigned integer represented either as a Python integer or a vector of integers. Seeds shorter than 1024-bit will be padded. The padding, the internal structure of a seed and the way a seed is converted to a state are all opaque (unspecified). The only semantics specification of seeds is that two different seeds are likely to produce two independent generators (but no guarantee).

Args:

  • seed: the seed for the RNG.
  • alg: (optional) the RNG algorithm. If None, it will be auto-selected. See __init__ for its possible values.

Returns:

The new generator.

from_state

View source

@classmethod
from_state(
    state, alg
)

Creates a generator from a state.

See __init__ for description of state and alg.

Args:

  • state: the new state.
  • alg: the RNG algorithm.

Returns:

The new generator.

make_seeds

View source

make_seeds(
    count=1
)

Generates seeds for stateless random ops.

For example:

seeds = get_global_generator().make_seeds(count=10)
for i in range(10):
  seed = seeds[:, i]
  numbers = stateless_random_normal(shape=[2, 3], seed=seed)
  ...

Args:

  • count: the number of seed pairs (note that stateless random ops need a pair of seeds to invoke).

Returns:

A tensor of shape [2, count] and dtype int64.

normal

View source

normal(
    shape, mean=0.0, stddev=1.0, dtype=tf.dtypes.float32, name=None
)

Outputs random values from a normal distribution.

Args:

  • shape: A 1-D integer Tensor or Python array. The shape of the output tensor.
  • mean: A 0-D Tensor or Python value of type dtype. The mean of the normal distribution.
  • stddev: A 0-D Tensor or Python value of type dtype. The standard deviation of the normal distribution.
  • dtype: The type of the output.
  • name: A name for the operation (optional).

Returns:

A tensor of the specified shape filled with random normal values.

reset

View source

reset(
    state
)

Resets the generator by a new state.

See __init__ for the meaning of "state".

Args:

  • state: the new state.

reset_from_key_counter

View source

reset_from_key_counter(
    key, counter
)

Resets the generator by a new key-counter pair.

See from_key_counter for the meaning of "key" and "counter".

Args:

  • key: the new key.
  • counter: the new counter.

reset_from_seed

View source

reset_from_seed(
    seed
)

Resets the generator by a new seed.

See from_seed for the meaning of "seed".

Args:

  • seed: the new seed.

skip

View source

skip(
    delta
)

Advance the counter of a counter-based RNG.

Args:

  • delta: the amount of advancement. The state of the RNG after skip(n) will be the same as that after normal([n]) (or any other distribution). The actual increment added to the counter is an unspecified implementation detail.

split

View source

split(
    count=1
)

Returns a list of independent Generator objects.

Two generators are independent of each other in the sense that the random-number streams they generate don't have statistically detectable correlations. The new generators are also independent of the old one. The old generator's state will be changed (like other random-number generating methods), so two calls of split will return different new generators.

For example:

gens = get_global_generator().split(count=10)
for gen in gens:
  numbers = gen.normal(shape=[2, 3])
  # ...
gens2 = get_global_generator().split(count=10)
# gens2 will be different from gens

The new generators will be put on the current device (possible different from the old generator's), for example:

with tf.device("/device:CPU:0"):
  gen = Generator(seed=1234)  # gen is on CPU
with tf.device("/device:GPU:0"):
  gens = gen.split(count=10)  # gens are on GPU

Args:

  • count: the number of generators to return.

Returns:

A list (length count) of Generator objects independent of each other. The new generators have the same RNG algorithm as the old one.

truncated_normal

View source

truncated_normal(
    shape, mean=0.0, stddev=1.0, dtype=tf.dtypes.float32, name=None
)

Outputs random values from a truncated normal distribution.

The generated values follow a normal distribution with specified mean and standard deviation, except that values whose magnitude is more than 2 standard deviations from the mean are dropped and re-picked.

Args:

  • shape: A 1-D integer Tensor or Python array. The shape of the output tensor.
  • mean: A 0-D Tensor or Python value of type dtype. The mean of the truncated normal distribution.
  • stddev: A 0-D Tensor or Python value of type dtype. The standard deviation of the normal distribution, before truncation.
  • dtype: The type of the output.
  • name: A name for the operation (optional).

Returns:

A tensor of the specified shape filled with random truncated normal values.

uniform

View source

uniform(
    shape, minval=0, maxval=None, dtype=tf.dtypes.float32, name=None
)

Outputs random values from a uniform distribution.

The generated values follow a uniform distribution in the range [minval, maxval). The lower bound minval is included in the range, while the upper bound maxval is excluded. (For float numbers especially low-precision types like bfloat16, because of rounding, the result may sometimes include maxval.)

For floats, the default range is [0, 1). For ints, at least maxval must be specified explicitly.

In the integer case, the random integers are slightly biased unless maxval - minval is an exact power of two. The bias is small for values of maxval - minval significantly smaller than the range of the output (either 2**32 or 2**64).

Args:

  • shape: A 1-D integer Tensor or Python array. The shape of the output tensor.
  • minval: A 0-D Tensor or Python value of type dtype. The lower bound on the range of random values to generate. Defaults to 0.
  • maxval: A 0-D Tensor or Python value of type dtype. The upper bound on the range of random values to generate. Defaults to 1 if dtype is floating point.
  • dtype: The type of the output.
  • name: A name for the operation (optional).

Returns:

A tensor of the specified shape filled with random uniform values.

Raises:

  • ValueError: If dtype is integral and maxval is not specified.

uniform_full_int

View source

uniform_full_int(
    shape, dtype=tf.dtypes.uint64, name=None
)

Uniform distribution on an integer type's entire range.

The other method uniform only covers the range [minval, maxval), which cannot be dtype's full range because maxval is of type dtype.

Args:

  • shape: the shape of the output.
  • dtype: (optional) the integer type, default to uint64.
  • name: (optional) the name of the node.

Returns:

A tensor of random numbers of the required shape.