<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/experimental/nn/util/random_variable.py#L28-L139) |

`RandomVariable` supports random variable semantics for TFP distributions.

Inherits From: [`DeferredTensor`](https://www.tensorflow.org/probability/api_docs/python/tfp/util/DeferredTensor)

    tfp.experimental.nn.util.RandomVariable(
        distribution,
        convert_to_tensor_fn=https://www.tensorflow.org/probability/api_docs/python/tfp/distributions/Distribution#sample,
        dtype=None,
        shape=None,
        name=None
    )

The `RandomVariable` class memoizes concretizations of TFP distribution-like
objects so that random draws can be re-triggered on-demand, i.e., by calling
`reset`. For more details type `help(tfp.util.DeferredTensor)`.

#### Examples

    # In this example we see the memoization semantics in action.
    tfd = tfp.distributions
    tfn = tfp.experimental.nn
    x = tfn.util.RandomVariable(tfd.Normal(0, 1))
    x_ = tf.convert_to_tensor(x)
    x _ + 1. == x + 1.
    # ==> True; `x` always has the same value until reset.
    x.reset()
    tf.convert_to_tensor(x) == x_
    # ==> False; `x` was reset which triggers a new sample.

    # In this example we see how to concretize with different semantics.
    tfd = tfp.distributions
    tfn = tfp.experimental.nn
    x = tfn.util.RandomVariable(
        tfd.Bernoulli(probs=[[0.25], [0.5]]),
        convert_to_tensor_fn=tfd.Distribution.mean,
        dtype=tf.float32,
        shape=[2, 1],
        name='x')
    tf.convert_to_tensor(x)
    # ==> [[0.25], [0.5]]
    x.shape
    # ==> [2, 1]
    x.dtype
    # ==> tf.float32
    x.name
    # ==> 'x'

    # In this example we see a common pitfall: accessing the memoized value from a
    # different graph context.
    tfd = tfp.distributions
    tfn = tfp.experimental.nn
    x = tfn.util.RandomVariable(tfd.Normal(0, 1))
    @tf.function(autograph=False, jit_compile=True)
    def run():
      return tf.convert_to_tensor(x)
    first = run()
    second = tf.convert_to_tensor(x)
    # raises ValueError:
    #   "You are attempting to access a memoized value from a different
    #   graph context. Please call `this.reset()` before accessing a
    #   memoized value from a different graph context."
    x.reset()
    third = tf.convert_to_tensor(x)
    # ==> No exception.
    first == third
    # ==> False

<br />

<br />

<br />

| ## Args ||
|---|---|
| `distribution` | TFP distribution-like object which is passed into the `convert_to_tensor_fn` whenever this object is evaluated in `Tensor`-like contexts. |
| `convert_to_tensor_fn` | Python `callable` which takes one argument, the `distribution` and returns a `Tensor` of type `dtype` and shape `shape`. Default value: [`tfp.distributions.Distribution.sample`](https://www.tensorflow.org/probability/api_docs/python/tfp/distributions/Distribution#sample). |
| `dtype` | TF `dtype` equivalent to what would otherwise be `convert_to_tensor_fn(distribution).dtype`. Default value: `None` (i.e., `distribution.dtype`). |
| `shape` | [`tf.TensorShape`](https://www.tensorflow.org/api_docs/python/tf/TensorShape)-like object compatible with what would otherwise be `convert_to_tensor_fn(distribution).shape`. Default value: `'None'` (i.e., unspecified static shape). |
| `name` | Python `str` representing this object's `name`; used only in graph mode. Default value: `None` (i.e., `distribution.name`) |

<br />

<br />

<br />

<br />

| ## Attributes ||
|---|---|
| `also_track` | Additional variables tracked by tf.Module in self.trainable_variables. |
| `convert_to_tensor_fn` | <br /> <br /> |
| `distribution` | <br /> <br /> |
| `dtype` | Represents the type of the elements in a `Tensor`. |
| `name` | The string name of this object. |
| `name_scope` | Returns a [`tf.name_scope`](https://www.tensorflow.org/api_docs/python/tf/name_scope) instance for this class. |
| `non_trainable_variables` | Sequence of non-trainable variables owned by this module and its submodules. <br /> > [!NOTE] > **Note:** this method uses reflection to find variables on the current instance and submodules. For performance reasons you may wish to cache the result of calling this method if you don't expect the return value to change. |
| `pretransformed_input` | Input to `transform_fn`. |
| `shape` | Represents the shape of a `Tensor`. |
| `submodules` | Sequence of all sub-modules. Submodules are modules which are properties of this module, or found as properties of modules which are properties of this module (and so on). a = tf.Module() b = tf.Module() c = tf.Module() a.b = b b.c = c list(a.submodules) == [b, c] True list(b.submodules) == [c] True list(c.submodules) == [] True <br /> |
| `trainable_variables` | Sequence of trainable variables owned by this module and its submodules. <br /> > [!NOTE] > **Note:** this method uses reflection to find variables on the current instance and submodules. For performance reasons you may wish to cache the result of calling this method if you don't expect the return value to change. |
| `transform_fn` | Function which characterizes the `Tensor`ization of this object. |
| `variables` | Sequence of variables owned by this module and its submodules. > [!NOTE] > **Note:** this method uses reflection to find variables on the current instance and submodules. For performance reasons you may wish to cache the result of calling this method if you don't expect the return value to change. |

## Methods

### `is_unset`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/experimental/nn/util/random_variable.py#L137-L139)

    is_unset()

Returns `True` if there is no memoized value and `False` otherwise.

### `numpy`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L312-L318)

    numpy()

Returns (copy of) deferred values as a NumPy array or scalar.

### `reset`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/experimental/nn/util/random_variable.py#L133-L135)

    reset()

Removes memoized value which triggers re-eval on subsequent reads.

### `set_shape`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L320-L336)

    set_shape(
        shape
    )

Updates the shape of this pretransformed_input.

This method can be called multiple times, and will merge the given `shape`
with the current shape of this object. It can be used to provide additional
information about the shape of this object that cannot be inferred from the
graph alone.

<br />

<br />

<br />

| Args ||
|---|---|
| `shape` | A `TensorShape` representing the shape of this `pretransformed_input`, a `TensorShapeProto`, a list, a tuple, or None. |

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `ValueError` | If `shape` is not compatible with the current shape of this `pretransformed_input`. |

<br />

### `with_name_scope`

    @classmethod
    with_name_scope(
        method
    )

Decorator to automatically enter the module name scope.

    class MyModule(tf.Module):
      @tf.Module.with_name_scope
      def __call__(self, x):
        if not hasattr(self, 'w'):
          self.w = tf.Variable(tf.random.normal([x.shape[1], 3]))
        return tf.matmul(x, self.w)

Using the above module would produce [`tf.Variable`](https://www.tensorflow.org/api_docs/python/tf/Variable)s and [`tf.Tensor`](https://www.tensorflow.org/api_docs/python/tf/Tensor)s whose
names included the module name:

    mod = MyModule()
    mod(tf.ones([1, 2]))
    <tf.Tensor: shape=(1, 3), dtype=float32, numpy=..., dtype=float32)>
    mod.w
    <tf.Variable 'my_module/Variable:0' shape=(2, 3) dtype=float32,
    numpy=..., dtype=float32)>

<br />

<br />

<br />

| Args ||
|---|---|
| `method` | The method to wrap. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| The original method wrapped such that it enters the module's name scope. ||

<br />

### `__abs__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __abs__(
        *args, **kwargs
    )

### `__add__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __add__(
        *args, **kwargs
    )

### `__and__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __and__(
        *args, **kwargs
    )

### `__array__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L373-L378)

    __array__(
        dtype=None
    )

### `__bool__`

    __bool__()

Dummy method to prevent a tensor from being used as a Python `bool`.

This overload raises a `TypeError` when the user inadvertently
treats a `Tensor` as a boolean (most commonly in an `if` or `while`
statement), in code that was not converted by AutoGraph. For example:

    if tf.constant(True):  # Will raise.
      # ...

    if tf.constant(5) < tf.constant(7):  # Will raise.
      # ...

<br />

<br />

<br />

| Raises ||
|---|---|
| `TypeError`. ||

<br />

### `__div__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __div__(
        *args, **kwargs
    )

### `__floordiv__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __floordiv__(
        *args, **kwargs
    )

### `__ge__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __ge__(
        *args, **kwargs
    )

### `__getitem__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __getitem__(
        *args, **kwargs
    )

### `__gt__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __gt__(
        *args, **kwargs
    )

### `__invert__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __invert__(
        *args, **kwargs
    )

### `__iter__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __iter__(
        *args, **kwargs
    )

### `__le__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __le__(
        *args, **kwargs
    )

### `__lt__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __lt__(
        *args, **kwargs
    )

### `__matmul__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __matmul__(
        *args, **kwargs
    )

### `__mod__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __mod__(
        *args, **kwargs
    )

### `__mul__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __mul__(
        *args, **kwargs
    )

### `__neg__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __neg__(
        *args, **kwargs
    )

### `__nonzero__`

    __nonzero__()

Dummy method to prevent a tensor from being used as a Python `bool`.

This is the Python 2.x counterpart to `__bool__()` above.

<br />

<br />

<br />

| Raises ||
|---|---|
| `TypeError`. ||

<br />

### `__or__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __or__(
        *args, **kwargs
    )

### `__pow__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __pow__(
        *args, **kwargs
    )

### `__radd__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __radd__(
        *args, **kwargs
    )

### `__rand__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __rand__(
        *args, **kwargs
    )

### `__rdiv__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __rdiv__(
        *args, **kwargs
    )

### `__rfloordiv__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __rfloordiv__(
        *args, **kwargs
    )

### `__rmatmul__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __rmatmul__(
        *args, **kwargs
    )

### `__rmod__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __rmod__(
        *args, **kwargs
    )

### `__rmul__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __rmul__(
        *args, **kwargs
    )

### `__ror__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __ror__(
        *args, **kwargs
    )

### `__rpow__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __rpow__(
        *args, **kwargs
    )

### `__rsub__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __rsub__(
        *args, **kwargs
    )

### `__rtruediv__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __rtruediv__(
        *args, **kwargs
    )

### `__rxor__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __rxor__(
        *args, **kwargs
    )

### `__sub__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __sub__(
        *args, **kwargs
    )

### `__truediv__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __truediv__(
        *args, **kwargs
    )

### `__xor__`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/util/deferred_tensor.py#L74-L77)

    __xor__(
        *args, **kwargs
    )