Help protect the Great Barrier Reef with TensorFlow on Kaggle Join Challenge

tf.random.Generator

View source on GitHub

Random-number generator.

Example:

Creating a generator from a seed:

g = tf.random.Generator.from_seed(1234)
g.normal(shape=(2, 3))
<tf.Tensor: shape=(2, 3), dtype=float32, numpy=
array([[ 0.9356609 ,  1.0854305 , -0.93788373],
       [-0.5061547 ,  1.3169702 ,  0.7137579 ]], dtype=float32)>

Creating a generator from a non-deterministic state:

g = tf.random.Generator.from_non_deterministic_state()
g.normal(shape=(2, 3))
<tf.Tensor: shape=(2, 3), dtype=float32, numpy=...>

All the constructors allow explicitly choosing an Random-Number-Generation (RNG) algorithm. Supported algorithms are "philox" and "threefry". For example:

g = tf.random.Generator.from_seed(123, alg="philox")
g.normal(shape=(2, 3))
<tf.Tensor: shape=(2, 3), dtype=float32, numpy=
array([[ 0.8673864 , -0.29899067, -0.9310337 ],
       [-1.5828488 ,  1.2481191 , -0.6770643 ]], dtype=float32)>

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 different devices.

This class uses a tf.Variable to manage its internal state. Every time random numbers are generated, the state of the generator will change. For example:

g = tf.random.Generator.from_seed(1234)
g.state
<tf.Variable ... numpy=array([1234,    0,    0])>
g.normal(shape=(2, 3))
<...>
g.state
<tf.Variable ... numpy=array([2770,    0,    0])>

The shape of the state is algorithm-specific.

There is also a global generator:

g = tf.random.get_global_generator()
g.normal(shape=(2, 3))
<tf.Tensor: shape=(2, 3), dtype=float32, numpy=...>

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. If it's a variable, the generator will reuse it instead of creating a new variable.
alg the RNG algorithm. Possible values are tf.random.Algorithm.PHILOX for the Philox algorithm and tf.random.Algorithm.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]). The string names "philox" and "threefry" can also be used. Note PHILOX guarantees the same numbers are produced (given the same random state) across all architectures (CPU, GPU, XLA etc).

algorithm The RNG algorithm id (a Python integer or scalar integer Tensor).
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

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]

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


counts = ... # Shape [3, 1, 2]
probs = ...  # Shape [1, 4, 2]
shape = [3, 4, 3, 4, 2]
rng = tf.random.Generator.from_seed(seed=1717)
# Sample shape will be [3, 4, 3, 4, 2]
binomial_samples = rng.binomial(shape=shape, counts=counts, probs=probs)

Args
shape A 1-D integer Tensor or Python array. The shape of the output tensor.
counts Tensor. The counts of the binomial distribution. Must be broadcastable with probs, and broadcastable with the rightmost dimensions of shape.
probs Tensor. The probability of success for the binomial distribution. Must be broadcastable with counts and broadcastable with the rightmost dimensions of 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