tf.random.experimental.Generator

View source on GitHub

Random-number generator.

Inherits From: Checkpointable

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.

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)

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".

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.

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).

from_state

View source

@classmethod
from_state(
    state, alg
)

Creates a generator from a state.

See __init__ for description of state and alg.

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)
  ...

normal

View source

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

Outputs random values from a normal distribution.

reset

View source

reset(
    state
)

Resets the generator by a new state.

See __init__ for the meaning of "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".

reset_from_seed

View source

reset_from_seed(
    seed
)

Resets the generator by a new seed.

See from_seed for the meaning of "seed".

skip

View source

skip(
    delta
)

Advance the counter of a counter-based RNG.

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

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.

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).

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.