Attend the Women in ML Symposium on December 7

# tfp.bijectors.UnitVector

Stay organized with collections Save and categorize content based on your preferences.

Bijector mapping vectors onto the unit sphere.

This bijector maps points in n-dimensional space to the unit sphere in (n + 1)-dimensional space via the inverse stereographic projection from the point (0, ..., 0, 1).

#### The forward map is:

f(x0, ..., x{n-1}) = (2x0/(s^2 + 1), ..., 2x{n-1}/(s^2 + 1), (s^2 - 1)/(s^2 + 1))

where s^2 = x0^2 + ... + x{n-1}^2.

And the inverse map is

f^{-1}(y_0, ..., y_n) = (y_0/(1 - yn), ..., y{n-1}/(1 - y_n)).

#### Example Use:

``````UnitVector().forward([2., 1, 2])
# Result: [0.4, 0.2, 0.4, 0.8]

UnitVector().inverse([0.4, 0.2, 0.4, 0.8])
# Result: [2., 1., 2.]
``````

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

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

`dtype`

`forward_min_event_ndims` Returns the minimal number of dimensions bijector.forward operates on.

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.

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.

`name` Returns the string name of this `Bijector`.
`name_scope` Returns a `tf.name_scope` instance for this class.
`non_trainable_variables` Sequence of non-trainable variables owned by this module and its submodules.
`parameters` Dictionary of parameters used to instantiate this `Bijector`.
`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`
```

`trainable_variables` Sequence of trainable variables owned by this module and its submodules.

`validate_args` Returns True if Tensor arguments will be validated.
`variables` Sequence of variables owned by this module and its submodules.

## Methods

### `copy`

View source

Creates a copy of the bijector.

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

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

### `experimental_batch_shape`

View source

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

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

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

### `experimental_batch_shape_tensor`

View source

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

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