# tf.random.experimental.Generator

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L171-L672) |

Random-number generator.

Inherits From: [`Checkpointable`](https://www.tensorflow.org/versions/r1.15/api_docs/python/tf/contrib/checkpoint/Checkpointable)

#### View aliases


**Compat aliases for migration**

See
[Migration guide](https://www.tensorflow.org/guide/migrate) for
more details.

[`tf.compat.v1.random.experimental.Generator`](https://www.tensorflow.org/api_docs/python/tf/random/Generator), \`tf.compat.v2.random.experimental.Generator\`

<br />

    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.

<br />

<br />

<br />

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

<br />

<br />

<br />

<br />

| ## Attributes ||
|---|---|
| `algorithm` | The RNG algorithm. |
| `key` | The 'key' part of the state of a counter-based RNG. <br /> 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. |

<br />

## Methods

### `binomial`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L535-L583)

    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)

<br />

<br />

<br />

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

<br />

<br />

<br />

<br />

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

<br />

### `from_key_counter`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L278-L301)

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

<br />

<br />

<br />

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

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| The new generator. ||

<br />

### `from_non_deterministic_state`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L258-L276)

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

<br />

<br />

<br />

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

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| The new generator. ||

<br />

### `from_seed`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L233-L256)

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

<br />

<br />

<br />

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

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| The new generator. ||

<br />

### `from_state`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L218-L231)

    @classmethod
    from_state(
        state, alg
    )

Creates a generator from a state.

See `__init__` for description of `state` and `alg`.

<br />

<br />

<br />

| Args ||
|---|---|
| `state` | the new state. |
| `alg` | the RNG algorithm. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| The new generator. ||

<br />

### `make_seeds`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L594-L622)

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

<br />

<br />

<br />

| Args ||
|---|---|
| `count` | the number of seed pairs (note that stateless random ops need a pair of seeds to invoke). |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A tensor of shape \[2, count\] and dtype int64. ||

<br />

### `normal`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L394-L416)

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

Outputs random values from a normal distribution.

<br />

<br />

<br />

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

<br />

<br />

<br />

<br />

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

<br />

### `reset`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L303-L313)

    reset(
        state
    )

Resets the generator by a new state.

See `__init__` for the meaning of "state".

<br />

<br />

<br />

| Args ||
|---|---|
| `state` | the new state. |

<br />

### `reset_from_key_counter`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L326-L342)

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

<br />

<br />

<br />

| Args ||
|---|---|
| `key` | the new key. |
| `counter` | the new counter. |

<br />

### `reset_from_seed`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L315-L324)

    reset_from_seed(
        seed
    )

Resets the generator by a new seed.

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

<br />

<br />

<br />

| Args ||
|---|---|
| `seed` | the new seed. |

<br />

### `skip`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L381-L390)

    skip(
        delta
    )

Advance the counter of a counter-based RNG.

<br />

<br />

<br />

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

<br />

### `split`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L624-L672)

    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

<br />

<br />

<br />

| Args ||
|---|---|
| `count` | the number of generators to return. |

<br />

<br />

<br />

<br />

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

<br />

### `truncated_normal`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L422-L454)

    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.

<br />

<br />

<br />

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

<br />

<br />

<br />

<br />

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

<br />

### `uniform`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L460-L511)

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

<br />

<br />

<br />

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

<br />

<br />

<br />

<br />

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

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If `dtype` is integral and `maxval` is not specified. |

<br />

### `uniform_full_int`

[View source](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/stateful_random_ops.py#L513-L533)

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

<br />

<br />

<br />

| Args ||
|---|---|
| `shape` | the shape of the output. |
| `dtype` | (optional) the integer type, default to uint64. |
| `name` | (optional) the name of the node. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A tensor of random numbers of the required shape. ||

<br />