# tf_agents.distributions.tanh_bijector_stable.Tanh

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/agents/blob/v0.19.0/tf_agents/distributions/tanh_bijector_stable.py#L31-L84) |

Bijector that computes `Y = tanh(X)`, therefore `Y in (-1, 1)`.

    tf_agents.distributions.tanh_bijector_stable.Tanh(
        validate_args=False, name='tanh'
    )

This can be achieved by an affine transform of the Sigmoid bijector, i.e.,
it is equivalent to

    tfb.Chain([tfb.Affine(shift=-1, scale=2.),
               tfb.Sigmoid(),
               tfb.Affine(scale=2.)])

However, using the `Tanh` bijector directly is slightly faster and more
numerically stable.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `graph_parents` | Python list of graph prerequisites of this `Bijector`. |
| `is_constant_jacobian` | Python `bool` indicating that the Jacobian matrix is not a function of the input. |
| `validate_args` | Python `bool`, default `False`. Whether to validate input with asserts. If `validate_args` is `False`, and the inputs are invalid, correct behavior is not guaranteed. |
| `dtype` | `tf.dtype` supported by this `Bijector`. `None` means dtype is not enforced. For multipart bijectors, this value is expected to be the same for all elements of the input and output structures. |
| `forward_min_event_ndims` | Python `integer` (structure) indicating the minimum number of dimensions on which `forward` operates. |
| `inverse_min_event_ndims` | Python `integer` (structure) indicating the minimum number of dimensions on which `inverse` operates. Will be set to `forward_min_event_ndims` by default, if no value is provided. |
| `experimental_use_kahan_sum` | Python `bool`. When `True`, use Kahan summation to aggregate log-det jacobians from independent underlying log-det jacobian values, which improves against the precision of a naive float32 sum. This can be noticeable in particular for large dimensions in float32. See CPU caveat on [`tfp.math.reduce_kahan_sum`](https://www.tensorflow.org/probability/api_docs/python/tfp/math/reduce_kahan_sum). |
| `parameters` | Python `dict` of parameters used to instantiate this `Bijector`. Bijector instances with identical types, names, and `parameters` share an input/output cache. `parameters` dicts are keyed by strings and are identical if their keys are identical and if corresponding values have identical hashes (or object ids, for unhashable objects). |
| `name` | The name to give Ops created by the initializer. |

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `ValueError` | If neither `forward_min_event_ndims` and `inverse_min_event_ndims` are specified, or if either of them is negative. |
| `ValueError` | If a member of `graph_parents` is not a `Tensor`. |

<br />

<br />

<br />

<br />

| ## Attributes ||
|---|---|
| `dtype` | <br /> <br /> |
| `forward_min_event_ndims` | Returns the minimal number of dimensions bijector.forward operates on. <br /> Multipart bijectors return structured `ndims`, which indicates the expected structure of their inputs. Some multipart bijectors, notably Composites, may return structures of `None`. |
| `graph_parents` | Returns this `Bijector`'s graph_parents as a Python list. |
| `inverse_min_event_ndims` | Returns the minimal number of dimensions bijector.inverse operates on. <br /> Multipart bijectors return structured `event_ndims`, which indicates the expected structure of their outputs. Some multipart bijectors, notably Composites, may return structures of `None`. |
| `is_constant_jacobian` | Returns true iff the Jacobian matrix is not a function of x. <br /> > [!NOTE] > **Note:** Jacobian matrix is either constant for both forward and inverse or neither. |
| `parameters` | Dictionary of parameters used to instantiate this `Bijector`. |
| `validate_args` | Returns True if Tensor arguments will be validated. |

## Methods

### `copy`

    copy(
        **override_parameters_kwargs
    )

Creates a copy of the bijector.

> [!NOTE]
> **Note:** the copy bijector may continue to depend on the original initialization arguments.

<br />

<br />

<br />

| Args ||
|---|---|
| `**override_parameters_kwargs` | String/value dictionary of initialization arguments to override with new values. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `bijector` | A new instance of `type(self)` initialized from the union of self.parameters and override_parameters_kwargs, i.e., `dict(self.parameters, **override_parameters_kwargs)`. |

<br />

### `experimental_batch_shape`

    experimental_batch_shape(
        x_event_ndims=None, y_event_ndims=None
    )

Returns the batch shape of this bijector for inputs of the given rank.

The batch shape of a bijector decribes the set of distinct
transformations it represents on events of a given size. For example: the
bijector `tfb.Scale([1., 2.])` has batch shape `[2]` for scalar events
(`event_ndims = 0`), because applying it to a scalar event produces
two scalar outputs, the result of two different scaling transformations.
The same bijector has batch shape `[]` for vector events, because applying
it to a vector produces (via elementwise multiplication) a single vector
output.

Bijectors that operate independently on multiple state parts, such as
`tfb.JointMap`, must broadcast to a coherent batch shape. Some events may
not be valid: for example, the bijector
`tfd.JointMap([tfb.Scale([1., 2.]), tfb.Scale([1., 2., 3.])])` does not
produce a valid batch shape when `event_ndims = [0, 0]`, since the batch
shapes of the two parts are inconsistent. The same bijector
does define valid batch shapes of `[]`, `[2]`, and `[3]` if `event_ndims`
is `[1, 1]`, `[0, 1]`, or `[1, 0]`, respectively.

Since transforming a single event produces a scalar log-det-Jacobian, the
batch shape of a bijector with non-constant Jacobian is expected to equal
the shape of `forward_log_det_jacobian(x, event_ndims=x_event_ndims)`
or `inverse_log_det_jacobian(y, event_ndims=y_event_ndims)`, for `x`
or `y` of the specified `ndims`.

<br />

<br />

<br />

| Args ||
|---|---|
| `x_event_ndims` | Optional Python `int` (structure) number of dimensions in a probabilistic event passed to `forward`; this must be greater than or equal to `self.forward_min_event_ndims`. If `None`, defaults to `self.forward_min_event_ndims`. Mutually exclusive with `y_event_ndims`. Default value: `None`. |
| `y_event_ndims` | Optional Python `int` (structure) number of dimensions in a probabilistic event passed to `inverse`; this must be greater than or equal to `self.inverse_min_event_ndims`. Mutually exclusive with `x_event_ndims`. Default value: `None`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `batch_shape` | `TensorShape` batch shape of this bijector for a value with the given event rank. May be unknown or partially defined. |

<br />

### `experimental_batch_shape_tensor`

    experimental_batch_shape_tensor(
        x_event_ndims=None, y_event_ndims=None
    )

Returns the batch shape of this bijector for inputs of the given rank.

The batch shape of a bijector decribes the set of distinct
transformations it represents on events of a given size. For example: the
bijector `tfb.Scale([1., 2.])` has batch shape `[2]` for scalar events
(`event_ndims = 0`), because applying it to a scalar event produces
two scalar outputs, the result of two different scaling transformations.
The same bijector has batch shape `[]` for vector events, because applying
it to a vector produces (via elementwise multiplication) a single vector
output.

Bijectors that operate independently on multiple state parts, such as
`tfb.JointMap`, must broadcast to a coherent batch shape. Some events may
not be valid: for example, the bijector
`tfd.JointMap([tfb.Scale([1., 2.]), tfb.Scale([1., 2., 3.])])` does not
produce a valid batch shape when `event_ndims = [0, 0]`, since the batch
shapes of the two parts are inconsistent. The same bijector
does define valid batch shapes of `[]`, `[2]`, and `[3]` if `event_ndims`
is `[1, 1]`, `[0, 1]`, or `[1, 0]`, respectively.

Since transforming a single event produces a scalar log-det-Jacobian, the
batch shape of a bijector with non-constant Jacobian is expected to equal
the shape of `forward_log_det_jacobian(x, event_ndims=x_event_ndims)`
or `inverse_log_det_jacobian(y, event_ndims=y_event_ndims)`, for `x`
or `y` of the specified `ndims`.

<br />

<br />

<br />

| Args ||
|---|---|
| `x_event_ndims` | Optional Python `int` (structure) number of dimensions in a probabilistic event passed to `forward`; this must be greater than or equal to `self.forward_min_event_ndims`. If `None`, defaults to `self.forward_min_event_ndims`. Mutually exclusive with `y_event_ndims`. Default value: `None`. |
| `y_event_ndims` | Optional Python `int` (structure) number of dimensions in a probabilistic event passed to `inverse`; this must be greater than or equal to `self.inverse_min_event_ndims`. Mutually exclusive with `x_event_ndims`. Default value: `None`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `batch_shape_tensor` | integer `Tensor` batch shape of this bijector for a value with the given event rank. |

<br />

### `experimental_compute_density_correction`

    experimental_compute_density_correction(
        x, tangent_space, backward_compat=False, **kwargs
    )

Density correction for this transformation wrt the tangent space, at x.

Subclasses of Bijector may call the most specific applicable
method of `TangentSpace`, based on whether the transformation is
dimension-preserving, coordinate-wise, a projection, or something
more general. The backward-compatible assumption is that the
transformation is dimension-preserving (goes from R\^n to R\^n).

<br />

<br />

<br />

| Args ||
|---|---|
| `x` | `Tensor` (structure). The point at which to calculate the density. |
| `tangent_space` | `TangentSpace` or one of its subclasses. The tangent to the support manifold at `x`. |
| `backward_compat` | `bool` specifying whether to assume that the Bijector is dimension-preserving. |
| `**kwargs` | Optional keyword arguments forwarded to tangent space methods. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `density_correction` | `Tensor` representing the density correction---in log space---under the transformation that this Bijector denotes. |

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| TypeError if `backward_compat` is False but no method of `TangentSpace` has been called explicitly. ||

<br />

### `forward`

    forward(
        x, name='forward', **kwargs
    )

Returns the forward `Bijector` evaluation, i.e., X = g(Y).

<br />

<br />

<br />

| Args ||
|---|---|
| `x` | `Tensor` (structure). The input to the 'forward' evaluation. |
| `name` | The name to give this op. |
| `**kwargs` | Named arguments forwarded to subclass implementation. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `Tensor` (structure). ||

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `TypeError` | if `self.dtype` is specified and `x.dtype` is not `self.dtype`. |
| `NotImplementedError` | if `_forward` is not implemented. |

<br />

### `forward_dtype`

    forward_dtype(
        dtype=UNSPECIFIED, name='forward_dtype', **kwargs
    )

Returns the dtype returned by `forward` for the provided input.

### `forward_event_ndims`

    forward_event_ndims(
        event_ndims, **kwargs
    )

Returns the number of event dimensions produced by `forward`.

<br />

<br />

<br />

| Args ||
|---|---|
| `event_ndims` | Structure of Python and/or Tensor `int`s, and/or `None` values. The structure should match that of `self.forward_min_event_ndims`, and all non-`None` values must be greater than or equal to the corresponding value in `self.forward_min_event_ndims`. |
| `**kwargs` | Optional keyword arguments forwarded to nested bijectors. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `forward_event_ndims` | Structure of integers and/or `None` values matching `self.inverse_min_event_ndims`. These are computed using 'prefer static' semantics: if any inputs are `None`, some or all of the outputs may be `None`, indicating that the output dimension could not be inferred (conversely, if all inputs are non-`None`, all outputs will be non-`None`). If all input `event_ndims` are Python `int`s, all of the (non-`None`) outputs will be Python `int`s; otherwise, some or all of the outputs may be `Tensor` `int`s. |

<br />

### `forward_event_shape`

    forward_event_shape(
        input_shape
    )

Shape of a single sample from a single batch as a `TensorShape`.

Same meaning as `forward_event_shape_tensor`. May be only partially defined.

<br />

<br />

<br />

| Args ||
|---|---|
| `input_shape` | `TensorShape` (structure) indicating event-portion shape passed into `forward` function. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `forward_event_shape_tensor` | `TensorShape` (structure) indicating event-portion shape after applying `forward`. Possibly unknown. |

<br />

### `forward_event_shape_tensor`

    forward_event_shape_tensor(
        input_shape, name='forward_event_shape_tensor'
    )

Shape of a single sample from a single batch as an `int32` 1D `Tensor`.

<br />

<br />

<br />

| Args ||
|---|---|
| `input_shape` | `Tensor`, `int32` vector (structure) indicating event-portion shape passed into `forward` function. |
| `name` | name to give to the op |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `forward_event_shape_tensor` | `Tensor`, `int32` vector (structure) indicating event-portion shape after applying `forward`. |

<br />

### `forward_log_det_jacobian`

    forward_log_det_jacobian(
        x, event_ndims=None, name='forward_log_det_jacobian', **kwargs
    )

Returns both the forward_log_det_jacobian.

<br />

<br />

<br />

| Args ||
|---|---|
| `x` | `Tensor` (structure). The input to the 'forward' Jacobian determinant evaluation. |
| `event_ndims` | Optional number of dimensions in the probabilistic events being transformed; this must be greater than or equal to `self.forward_min_event_ndims`. If `event_ndims` is specified, the log Jacobian determinant is summed to produce a scalar log-determinant for each event. Otherwise (if `event_ndims` is `None`), no reduction is performed. Multipart bijectors require *structured* event_ndims, such that the batch rank `rank(y[i]) - event_ndims[i]` is the same for all elements `i` of the structured input. In most cases (with the exception of `tfb.JointMap`) they further require that `event_ndims[i] - self.inverse_min_event_ndims[i]` is the same for all elements `i` of the structured input. Default value: `None` (equivalent to `self.forward_min_event_ndims`). |
| `name` | The name to give this op. |
| `**kwargs` | Named arguments forwarded to subclass implementation. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `Tensor` (structure), if this bijector is injective. If not injective this is not implemented. ||

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `TypeError` | if `y`'s dtype is incompatible with the expected output dtype. |
| `NotImplementedError` | if neither `_forward_log_det_jacobian` nor {`_inverse`, `_inverse_log_det_jacobian`} are implemented, or this is a non-injective bijector. |
| `ValueError` | if the value of `event_ndims` is not valid for this bijector. |

<br />

### `inverse`

    inverse(
        y, name='inverse', **kwargs
    )

Returns the inverse `Bijector` evaluation, i.e., X = g\^{-1}(Y).

<br />

<br />

<br />

| Args ||
|---|---|
| `y` | `Tensor` (structure). The input to the 'inverse' evaluation. |
| `name` | The name to give this op. |
| `**kwargs` | Named arguments forwarded to subclass implementation. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `Tensor` (structure), if this bijector is injective. If not injective, returns the k-tuple containing the unique `k` points `(x1, ..., xk)` such that `g(xi) = y`. ||

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `TypeError` | if `y`'s structured dtype is incompatible with the expected output dtype. |
| `NotImplementedError` | if `_inverse` is not implemented. |

<br />

### `inverse_dtype`

    inverse_dtype(
        dtype=UNSPECIFIED, name='inverse_dtype', **kwargs
    )

Returns the dtype returned by `inverse` for the provided input.

### `inverse_event_ndims`

    inverse_event_ndims(
        event_ndims, **kwargs
    )

Returns the number of event dimensions produced by `inverse`.

<br />

<br />

<br />

| Args ||
|---|---|
| `event_ndims` | Structure of Python and/or Tensor `int`s, and/or `None` values. The structure should match that of `self.inverse_min_event_ndims`, and all non-`None` values must be greater than or equal to the corresponding value in `self.inverse_min_event_ndims`. |
| `**kwargs` | Optional keyword arguments forwarded to nested bijectors. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `inverse_event_ndims` | Structure of integers and/or `None` values matching `self.forward_min_event_ndims`. These are computed using 'prefer static' semantics: if any inputs are `None`, some or all of the outputs may be `None`, indicating that the output dimension could not be inferred (conversely, if all inputs are non-`None`, all outputs will be non-`None`). If all input `event_ndims` are Python `int`s, all of the (non-`None`) outputs will be Python `int`s; otherwise, some or all of the outputs may be `Tensor` `int`s. |

<br />

### `inverse_event_shape`

    inverse_event_shape(
        output_shape
    )

Shape of a single sample from a single batch as a `TensorShape`.

Same meaning as `inverse_event_shape_tensor`. May be only partially defined.

<br />

<br />

<br />

| Args ||
|---|---|
| `output_shape` | `TensorShape` (structure) indicating event-portion shape passed into `inverse` function. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `inverse_event_shape_tensor` | `TensorShape` (structure) indicating event-portion shape after applying `inverse`. Possibly unknown. |

<br />

### `inverse_event_shape_tensor`

    inverse_event_shape_tensor(
        output_shape, name='inverse_event_shape_tensor'
    )

Shape of a single sample from a single batch as an `int32` 1D `Tensor`.

<br />

<br />

<br />

| Args ||
|---|---|
| `output_shape` | `Tensor`, `int32` vector (structure) indicating event-portion shape passed into `inverse` function. |
| `name` | name to give to the op |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `inverse_event_shape_tensor` | `Tensor`, `int32` vector (structure) indicating event-portion shape after applying `inverse`. |

<br />

### `inverse_log_det_jacobian`

    inverse_log_det_jacobian(
        y, event_ndims=None, name='inverse_log_det_jacobian', **kwargs
    )

Returns the (log o det o Jacobian o inverse)(y).

Mathematically, returns: `log(det(dX/dY))(Y)`. (Recall that: `X=g^{-1}(Y)`.)

Note that `forward_log_det_jacobian` is the negative of this function,
evaluated at `g^{-1}(y)`.

<br />

<br />

<br />

| Args ||
|---|---|
| `y` | `Tensor` (structure). The input to the 'inverse' Jacobian determinant evaluation. |
| `event_ndims` | Optional number of dimensions in the probabilistic events being transformed; this must be greater than or equal to `self.inverse_min_event_ndims`. If `event_ndims` is specified, the log Jacobian determinant is summed to produce a scalar log-determinant for each event. Otherwise (if `event_ndims` is `None`), no reduction is performed. Multipart bijectors require *structured* event_ndims, such that the batch rank `rank(y[i]) - event_ndims[i]` is the same for all elements `i` of the structured input. In most cases (with the exception of `tfb.JointMap`) they further require that `event_ndims[i] - self.inverse_min_event_ndims[i]` is the same for all elements `i` of the structured input. Default value: `None` (equivalent to `self.inverse_min_event_ndims`). |
| `name` | The name to give this op. |
| `**kwargs` | Named arguments forwarded to subclass implementation. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `ildj` | `Tensor`, if this bijector is injective. If not injective, returns the tuple of local log det Jacobians, `log(det(Dg_i^{-1}(y)))`, where `g_i` is the restriction of `g` to the `ith` partition `Di`. |

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `TypeError` | if `x`'s dtype is incompatible with the expected inverse-dtype. |
| `NotImplementedError` | if `_inverse_log_det_jacobian` is not implemented. |
| `ValueError` | if the value of `event_ndims` is not valid for this bijector. |

<br />

### `parameter_properties`

    @classmethod
    parameter_properties(
        dtype=tf.float32
    )

Returns a dict mapping constructor arg names to property annotations.

This dict should include an entry for each of the bijector's
`Tensor`-valued constructor arguments.

<br />

<br />

<br />

| Args ||
|---|---|
| `dtype` | Optional float `dtype` to assume for continuous-valued parameters. Some constraining bijectors require advance knowledge of the dtype because certain constants (e.g., `tfb.Softplus.low`) must be instantiated with the same dtype as the values to be transformed. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `parameter_properties` | A `str ->`tfp.python.internal.parameter_properties.ParameterProperties`dict mapping constructor argument names to`ParameterProperties\` instances. |

<br />

### `__call__`

    __call__(
        value, name=None, **kwargs
    )

Applies or composes the `Bijector`, depending on input type.

This is a convenience function which applies the `Bijector` instance in
three different ways, depending on the input:

1. If the input is a `tfd.Distribution` instance, return `tfd.TransformedDistribution(distribution=input, bijector=self)`.
2. If the input is a `tfb.Bijector` instance, return `tfb.Chain([self, input])`.
3. Otherwise, return `self.forward(input)`

<br />

<br />

<br />

| Args ||
|---|---|
| `value` | A `tfd.Distribution`, `tfb.Bijector`, or a (structure of) `Tensor`. |
| `name` | Python `str` name given to ops created by this function. |
| `**kwargs` | Additional keyword arguments passed into the created `tfd.TransformedDistribution`, `tfb.Bijector`, or `self.forward`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `composition` | A `tfd.TransformedDistribution` if the input was a `tfd.Distribution`, a `tfb.Chain` if the input was a `tfb.Bijector`, or a (structure of) `Tensor` computed by `self.forward`. |

<br />

#### Examples

    sigmoid = tfb.Reciprocal()(
        tfb.Shift(shift=1.)(
          tfb.Exp()(
            tfb.Scale(scale=-1.))))
    # ==> `tfb.Chain([
    #         tfb.Reciprocal(),
    #         tfb.Shift(shift=1.),
    #         tfb.Exp(),
    #         tfb.Scale(scale=-1.),
    #      ])`  # ie, `tfb.Sigmoid()`

    log_normal = tfb.Exp()(tfd.Normal(0, 1))
    # ==> `tfd.TransformedDistribution(tfd.Normal(0, 1), tfb.Exp())`

    tfb.Exp()([-1., 0., 1.])
    # ==> tf.exp([-1., 0., 1.])

### `__eq__`

    __eq__(
        other
    )

Return self==value.

### `__getitem__`

    __getitem__(
        slices
    )

### `__iter__`

    __iter__()