# tf.random.experimental.Generator

Random-number generator.

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.

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

`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

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

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

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

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

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

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

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

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

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

Resets the generator by a new seed.

See `from_seed` for the meaning of "seed".

Args
`seed` the new seed.

### `skip`

View source

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

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

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

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

[{ "type": "thumb-down", "id": "missingTheInformationINeed", "label":"Missing the information I need" },{ "type": "thumb-down", "id": "tooComplicatedTooManySteps", "label":"Too complicated / too many steps" },{ "type": "thumb-down", "id": "outOfDate", "label":"Out of date" },{ "type": "thumb-down", "id": "samplesCodeIssue", "label":"Samples / code issue" },{ "type": "thumb-down", "id": "otherDown", "label":"Other" }]
[{ "type": "thumb-up", "id": "easyToUnderstand", "label":"Easy to understand" },{ "type": "thumb-up", "id": "solvedMyProblem", "label":"Solved my problem" },{ "type": "thumb-up", "id": "otherUp", "label":"Other" }]