# tensorplay.distributions API

Source: https://www.tensorplay.cn/docs/api/tensorplay.distributions.html

## Functions 2

[#](#api-tensorplay.distributions.kl_divergence)

### kl_divergence

function[Full reference ↗](/docs/generated/tensorplay.distributions.kl_divergence.html)

```python
tensorplay.distributions.kl_divergence(p: Distribution, q: Distribution) → Tensor
```

Compute Kullback-Leibler divergence $KL(p \| q)$ between two distributions.

$$KL(p \| q) = \int p(x) \log\frac {p(x)} {q(x)} \,dx$$

Parameters:

- p ([Distribution](/docs/generated/tensorplay.distributions.Distribution.html#tensorplay.distributions.Distribution)) – A [Distribution](/docs/generated/tensorplay.distributions.Distribution.html#tensorplay.distributions.Distribution) object.

- q ([Distribution](/docs/generated/tensorplay.distributions.Distribution.html#tensorplay.distributions.Distribution)) – A [Distribution](/docs/generated/tensorplay.distributions.Distribution.html#tensorplay.distributions.Distribution) object.

Returns:

A batch of KL divergences of shape batch_shape.

Return type:

[Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)

Raises:

[NotImplementedError](https://docs.python.org/3/builtins/exceptions.html#NotImplementedError) – If the distribution types have not been registered via
    [register_kl()](/docs/generated/tensorplay.distributions.register_kl.html#tensorplay.distributions.register_kl).

KL divergence is currently implemented for the following distribution pairs:

- [Bernoulli](/docs/generated/tensorplay.distributions.Bernoulli.html#tensorplay.distributions.Bernoulli) and [Bernoulli](/docs/generated/tensorplay.distributions.Bernoulli.html#tensorplay.distributions.Bernoulli)

- [Bernoulli](/docs/generated/tensorplay.distributions.Bernoulli.html#tensorplay.distributions.Bernoulli) and [Poisson](/docs/generated/tensorplay.distributions.Poisson.html#tensorplay.distributions.Poisson)

- [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta) and [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta)

- [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta) and [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli)

- [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta) and [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential)

- [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta) and [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma)

- [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta) and [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal)

- [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta) and [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto)

- [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta) and [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform)

- [Binomial](/docs/generated/tensorplay.distributions.Binomial.html#tensorplay.distributions.Binomial) and [Binomial](/docs/generated/tensorplay.distributions.Binomial.html#tensorplay.distributions.Binomial)

- [Categorical](/docs/generated/tensorplay.distributions.Categorical.html#tensorplay.distributions.Categorical) and [Categorical](/docs/generated/tensorplay.distributions.Categorical.html#tensorplay.distributions.Categorical)

- [Cauchy](/docs/generated/tensorplay.distributions.Cauchy.html#tensorplay.distributions.Cauchy) and [Cauchy](/docs/generated/tensorplay.distributions.Cauchy.html#tensorplay.distributions.Cauchy)

- [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli) and [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli)

- [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli) and [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential)

- [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli) and [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal)

- [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli) and [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto)

- [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli) and [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform)

- [Dirichlet](/docs/generated/tensorplay.distributions.Dirichlet.html#tensorplay.distributions.Dirichlet) and [Dirichlet](/docs/generated/tensorplay.distributions.Dirichlet.html#tensorplay.distributions.Dirichlet)

- [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential) and [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta)

- [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential) and [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli)

- [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential) and [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential)

- [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential) and [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma)

- [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential) and [Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel)

- [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential) and [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal)

- [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential) and [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto)

- [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential) and [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform)

- [ExponentialFamily](/docs/generated/tensorplay.distributions.ExponentialFamily.html#tensorplay.distributions.ExponentialFamily) and [ExponentialFamily](/docs/generated/tensorplay.distributions.ExponentialFamily.html#tensorplay.distributions.ExponentialFamily)

- [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma) and [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta)

- [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma) and [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli)

- [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma) and [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential)

- [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma) and [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma)

- [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma) and [Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel)

- [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma) and [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal)

- [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma) and [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto)

- [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma) and [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform)

- [Geometric](/docs/generated/tensorplay.distributions.Geometric.html#tensorplay.distributions.Geometric) and [Geometric](/docs/generated/tensorplay.distributions.Geometric.html#tensorplay.distributions.Geometric)

- [Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel) and [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta)

- [Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel) and [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli)

- [Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel) and [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential)

- [Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel) and [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma)

- [Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel) and [Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel)

- [Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel) and [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal)

- [Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel) and [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto)

- [Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel) and [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform)

- [HalfNormal](/docs/generated/tensorplay.distributions.HalfNormal.html#tensorplay.distributions.HalfNormal) and [HalfNormal](/docs/generated/tensorplay.distributions.HalfNormal.html#tensorplay.distributions.HalfNormal)

- [Independent](/docs/generated/tensorplay.distributions.Independent.html#tensorplay.distributions.Independent) and [Independent](/docs/generated/tensorplay.distributions.Independent.html#tensorplay.distributions.Independent)

- [Laplace](/docs/generated/tensorplay.distributions.Laplace.html#tensorplay.distributions.Laplace) and [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta)

- [Laplace](/docs/generated/tensorplay.distributions.Laplace.html#tensorplay.distributions.Laplace) and [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli)

- [Laplace](/docs/generated/tensorplay.distributions.Laplace.html#tensorplay.distributions.Laplace) and [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential)

- [Laplace](/docs/generated/tensorplay.distributions.Laplace.html#tensorplay.distributions.Laplace) and [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma)

- [Laplace](/docs/generated/tensorplay.distributions.Laplace.html#tensorplay.distributions.Laplace) and [Laplace](/docs/generated/tensorplay.distributions.Laplace.html#tensorplay.distributions.Laplace)

- [Laplace](/docs/generated/tensorplay.distributions.Laplace.html#tensorplay.distributions.Laplace) and [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal)

- [Laplace](/docs/generated/tensorplay.distributions.Laplace.html#tensorplay.distributions.Laplace) and [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto)

- [Laplace](/docs/generated/tensorplay.distributions.Laplace.html#tensorplay.distributions.Laplace) and [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform)

- [LowRankMultivariateNormal](/docs/generated/tensorplay.distributions.LowRankMultivariateNormal.html#tensorplay.distributions.LowRankMultivariateNormal) and [LowRankMultivariateNormal](/docs/generated/tensorplay.distributions.LowRankMultivariateNormal.html#tensorplay.distributions.LowRankMultivariateNormal)

- [LowRankMultivariateNormal](/docs/generated/tensorplay.distributions.LowRankMultivariateNormal.html#tensorplay.distributions.LowRankMultivariateNormal) and [MultivariateNormal](/docs/generated/tensorplay.distributions.MultivariateNormal.html#tensorplay.distributions.MultivariateNormal)

- [MultivariateNormal](/docs/generated/tensorplay.distributions.MultivariateNormal.html#tensorplay.distributions.MultivariateNormal) and [LowRankMultivariateNormal](/docs/generated/tensorplay.distributions.LowRankMultivariateNormal.html#tensorplay.distributions.LowRankMultivariateNormal)

- [MultivariateNormal](/docs/generated/tensorplay.distributions.MultivariateNormal.html#tensorplay.distributions.MultivariateNormal) and [MultivariateNormal](/docs/generated/tensorplay.distributions.MultivariateNormal.html#tensorplay.distributions.MultivariateNormal)

- [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal) and [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta)

- [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal) and [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli)

- [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal) and [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential)

- [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal) and [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma)

- [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal) and [Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel)

- [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal) and [Laplace](/docs/generated/tensorplay.distributions.Laplace.html#tensorplay.distributions.Laplace)

- [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal) and [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal)

- [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal) and [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto)

- [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal) and [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform)

- [OneHotCategorical](/docs/generated/tensorplay.distributions.OneHotCategorical.html#tensorplay.distributions.OneHotCategorical) and [OneHotCategorical](/docs/generated/tensorplay.distributions.OneHotCategorical.html#tensorplay.distributions.OneHotCategorical)

- [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto) and [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta)

- [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto) and [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli)

- [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto) and [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential)

- [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto) and [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma)

- [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto) and [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal)

- [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto) and [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto)

- [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto) and [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform)

- [Poisson](/docs/generated/tensorplay.distributions.Poisson.html#tensorplay.distributions.Poisson) and [Bernoulli](/docs/generated/tensorplay.distributions.Bernoulli.html#tensorplay.distributions.Bernoulli)

- [Poisson](/docs/generated/tensorplay.distributions.Poisson.html#tensorplay.distributions.Poisson) and [Binomial](/docs/generated/tensorplay.distributions.Binomial.html#tensorplay.distributions.Binomial)

- [Poisson](/docs/generated/tensorplay.distributions.Poisson.html#tensorplay.distributions.Poisson) and [Poisson](/docs/generated/tensorplay.distributions.Poisson.html#tensorplay.distributions.Poisson)

- [TransformedDistribution](/docs/generated/tensorplay.distributions.TransformedDistribution.html#tensorplay.distributions.TransformedDistribution) and [TransformedDistribution](/docs/generated/tensorplay.distributions.TransformedDistribution.html#tensorplay.distributions.TransformedDistribution)

- [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform) and [Beta](/docs/generated/tensorplay.distributions.Beta.html#tensorplay.distributions.Beta)

- [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform) and [ContinuousBernoulli](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html#tensorplay.distributions.ContinuousBernoulli)

- [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform) and [Exponential](/docs/generated/tensorplay.distributions.Exponential.html#tensorplay.distributions.Exponential)

- [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform) and [Gamma](/docs/generated/tensorplay.distributions.Gamma.html#tensorplay.distributions.Gamma)

- [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform) and [Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel)

- [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform) and [Normal](/docs/generated/tensorplay.distributions.Normal.html#tensorplay.distributions.Normal)

- [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform) and [Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto)

- [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform) and [Uniform](/docs/generated/tensorplay.distributions.Uniform.html#tensorplay.distributions.Uniform)

[#](#api-tensorplay.distributions.register_kl)

### register_kl

function[Full reference ↗](/docs/generated/tensorplay.distributions.register_kl.html)

```python
tensorplay.distributions.register_kl(type_p, type_q)
```

Decorator to register a pairwise function with [kl_divergence()](/docs/generated/tensorplay.distributions.kl_divergence.html#tensorplay.distributions.kl_divergence).
Usage:

```
@register_kl(Normal, Normal)
def kl_normal_normal(p, q):
    # insert implementation here
```

Lookup returns the most specific (type,type) match ordered by subclass. If
the match is ambiguous, a RuntimeWarning is raised. For example to
resolve the ambiguous situation:

```
@register_kl(BaseP, DerivedQ)
def kl_version1(p, q): ...
@register_kl(DerivedP, BaseQ)
def kl_version2(p, q): ...
```

you should register a third most-specific implementation, e.g.:

```
register_kl(DerivedP, DerivedQ)(kl_version1)  # Break the tie.
```

Parameters:

- type_p ([type](https://docs.python.org/3/builtins/functions.html#type)) – A subclass of [Distribution](/docs/generated/tensorplay.distributions.Distribution.html#tensorplay.distributions.Distribution).

- type_q ([type](https://docs.python.org/3/builtins/functions.html#type)) – A subclass of [Distribution](/docs/generated/tensorplay.distributions.Distribution.html#tensorplay.distributions.Distribution).

## Classes 62

[#](#api-tensorplay.distributions.AbsTransform)

### AbsTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.AbsTransform.html)

```python
class tensorplay.distributions.AbsTransform(cache_size: int = 0)
```

Transform via the mapping $y = |x|$.

```python
forward_shape(shape)
```

Infers the shape of the forward computation, given the input shape.
Defaults to preserving shape.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
inverse_shape(shape)
```

Infers the shapes of the inverse computation, given the output shape.
Defaults to preserving shape.

```python
log_abs_det_jacobian(x, y)
```

Computes the log det jacobian log |dy/dx| given input and output.

```python
property sign: int
```

Returns the sign of the determinant of the Jacobian, if applicable.
In general this only makes sense for bijective transforms.

[#](#api-tensorplay.distributions.AffineTransform)

### AffineTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.AffineTransform.html)

```python
class tensorplay.distributions.AffineTransform(loc: Tensor | float, scale: Tensor | float, event_dim: int = 0, cache_size: int = 0)
```

Transform via the pointwise affine mapping $y = \text{loc} + \text{scale} \times x$.

Parameters:

- loc ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor) or [float](https://docs.python.org/3/builtins/functions.html#float)) – Location parameter.

- scale ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor) or [float](https://docs.python.org/3/builtins/functions.html#float)) – Scale parameter.

- event_dim ([int](https://docs.python.org/3/builtins/functions.html#int)) – Optional size of event_shape. This should be zero for univariate random variables, 1 for distributions over vectors, 2 for distributions over matrices, etc.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

[#](#api-tensorplay.distributions.Bernoulli)

### Bernoulli

class[Full reference ↗](/docs/generated/tensorplay.distributions.Bernoulli.html)

```python
class tensorplay.distributions.Bernoulli(probs: Tensor | bool | int | float | None = None, logits: Tensor | bool | int | float | None = None, validate_args: bool | None = None)
```

Creates a Bernoulli distribution parameterized by probs
or logits (but not both).

Samples are binary (0 or 1). They take the value 1 with probability p
and 0 with probability 1 - p.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Bernoulli(tensorplay.tensor([0.3]))
>>> m.sample()  # 30% chance 1; 70% chance 0
tensor([ 0.])
```

Parameters:

- probs (Number, [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – the probability of sampling 1

- logits (Number, [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – the log-odds of sampling 1

- validate_args ([bool](https://docs.python.org/3/builtins/functions.html#bool), optional) – whether to validate arguments, None by default

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Beta)

### Beta

class[Full reference ↗](/docs/generated/tensorplay.distributions.Beta.html)

```python
class tensorplay.distributions.Beta(concentration1: Tensor | float, concentration0: Tensor | float, validate_args: bool | None = None)
```

Beta distribution parameterized by concentration1 and concentration0.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Beta(tensorplay.tensor([0.5]), tensorplay.tensor([0.5]))
>>> m.sample()  # Beta distributed with concentration concentration1 and concentration0
tensor([ 0.1046])
```

Parameters:

- concentration1 ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – 1st concentration parameter of the distribution (often referred to as alpha)

- concentration0 ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – 2nd concentration parameter of the distribution (often referred to as beta)

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Binomial)

### Binomial

class[Full reference ↗](/docs/generated/tensorplay.distributions.Binomial.html)

```python
class tensorplay.distributions.Binomial(total_count: Tensor | int = 1, probs: Tensor | None = None, logits: Tensor | None = None, validate_args: bool | None = None)
```

Creates a Binomial distribution parameterized by total_count and
either probs or logits (but not both). total_count must be
broadcastable with probs/logits.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Binomial(100, tensorplay.tensor([0 , .2, .8, 1]))
>>> x = m.sample()
tensor([   0.,   22.,   71.,  100.])

>>> m = Binomial(tensorplay.tensor([[5.], [10.]]), tensorplay.tensor([0.5, 0.8]))
>>> x = m.sample()
tensor([[ 4.,  5.],
        [ 7.,  6.]])
```

Parameters:

- total_count ([int](https://docs.python.org/3/builtins/functions.html#int) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – number of Bernoulli trials

- probs ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – Event probabilities

- logits ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – Event log-odds

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Categorical)

### Categorical

class[Full reference ↗](/docs/generated/tensorplay.distributions.Categorical.html)

```python
class tensorplay.distributions.Categorical(probs: Tensor | None = None, logits: Tensor | None = None, validate_args: bool | None = None)
```

Creates a categorical distribution parameterized by either probs or
logits (but not both).

> **Note**
>
> It is equivalent to the distribution that tensorplay.multinomial() samples from.

Samples are integers from $\{0, \ldots, K-1\}$ where K is probs.size(-1).

If probs is 1-dimensional with length-K, each element is the relative probability
of sampling the class at that index.

If probs is N-dimensional, the first N-1 dimensions are treated as a batch of
relative probability vectors.

> **Note**
>
> The probs argument must be non-negative, finite and have a non-zero sum, and it will be normalized to sum to 1 along the last dimension. probs will return this normalized value. The logits argument will be interpreted as unnormalized log probabilities and can therefore be any real number. It will likewise be normalized so that the resulting probabilities sum to 1 along the last dimension. logits will return this normalized value.

See also: tensorplay.multinomial()

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Categorical(tensorplay.tensor([ 0.25, 0.25, 0.25, 0.25 ]))
>>> m.sample()  # equal probability of 0, 1, 2, 3
tensor(3)
```

Parameters:

- probs ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – event probabilities

- logits ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – event log probabilities (unnormalized)

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.CatTransform)

### CatTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.CatTransform.html)

```python
class tensorplay.distributions.CatTransform(tseq: Sequence[Transform], dim: int = 0, lengths: Sequence[int] | None = None, cache_size: int = 0)
```

Transform functor that applies a sequence of transforms tseq
component-wise to each submatrix at dim, of length lengths[dim],
in a way compatible with tensorplay.cat().

Example:

```
x0 = tensorplay.cat([tensorplay.range(1, 10), tensorplay.range(1, 10)], dim=0)
x = tensorplay.cat([x0, x0], dim=0)
t0 = CatTransform([ExpTransform(), identity_transform], dim=0, lengths=[10, 10])
t = CatTransform([t0, t0], dim=0, lengths=[20, 20])
y = t(x)
```

```python
forward_shape(shape)
```

Infers the shape of the forward computation, given the input shape.
Defaults to preserving shape.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
inverse_shape(shape)
```

Infers the shapes of the inverse computation, given the output shape.
Defaults to preserving shape.

```python
property sign: int
```

Returns the sign of the determinant of the Jacobian, if applicable.
In general this only makes sense for bijective transforms.

[#](#api-tensorplay.distributions.Cauchy)

### Cauchy

class[Full reference ↗](/docs/generated/tensorplay.distributions.Cauchy.html)

```python
class tensorplay.distributions.Cauchy(loc: Tensor | float, scale: Tensor | float, validate_args: bool | None = None)
```

Samples from a Cauchy (Lorentz) distribution. The distribution of the ratio of
independent normally distributed random variables with means 0 follows a
Cauchy distribution.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Cauchy(tensorplay.tensor([0.0]), tensorplay.tensor([1.0]))
>>> m.sample()  # sample from a Cauchy distribution with loc=0 and scale=1
tensor([ 2.3214])
```

Parameters:

- loc ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – mode or median of the distribution.

- scale ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – half width at half maximum.

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Chi2)

### Chi2

class[Full reference ↗](/docs/generated/tensorplay.distributions.Chi2.html)

```python
class tensorplay.distributions.Chi2(df: Tensor | float, validate_args: bool | None = None)
```

Creates a Chi-squared distribution parameterized by shape parameter df.
This is exactly equivalent to Gamma(alpha=0.5*df, beta=0.5)

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Chi2(tensorplay.tensor([1.0]))
>>> m.sample()  # Chi2 distributed with shape df=1
tensor([ 0.1046])
```

Parameters:

df ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – shape parameter of the distribution

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.ComposeTransform)

### ComposeTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.ComposeTransform.html)

```python
class tensorplay.distributions.ComposeTransform(parts: list[Transform], cache_size: int = 0)
```

Composes multiple transforms in a chain.
The transforms being composed are responsible for caching.

Parameters:

- parts (list of [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform)) – A list of transforms to compose.

- cache_size ([int](https://docs.python.org/3/builtins/functions.html#int)) – Size of cache. If zero, no caching is done. If one, the latest single value is cached. Only 0 and 1 are supported.

[#](#api-tensorplay.distributions.ContinuousBernoulli)

### ContinuousBernoulli

class[Full reference ↗](/docs/generated/tensorplay.distributions.ContinuousBernoulli.html)

```python
class tensorplay.distributions.ContinuousBernoulli(probs: Tensor | bool | int | float | None = None, logits: Tensor | bool | int | float | None = None, lims: tuple[float, float] = (0.499, 0.501), validate_args: bool | None = None)
```

Creates a continuous Bernoulli distribution parameterized by probs
or logits (but not both).

The distribution is supported in [0, 1] and parameterized by ‘probs’ (in
(0,1)) or ‘logits’ (real-valued). Note that, unlike the Bernoulli, ‘probs’
does not correspond to a probability and ‘logits’ does not correspond to
log-odds, but the same names are used due to the similarity with the
Bernoulli. See [1] for more details.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = ContinuousBernoulli(tensorplay.tensor([0.3]))
>>> m.sample()
tensor([ 0.2538])
```

Parameters:

- probs (Number, [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – (0,1) valued parameters

- logits (Number, [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – real valued parameters whose sigmoid matches ‘probs’

[1] The continuous Bernoulli: fixing a pervasive error in variational
autoencoders, Loaiza-Ganem G and Cunningham JP, NeurIPS 2019.
[https://arxiv.org/abs/1907.06845](https://arxiv.org/abs/1907.06845)

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
property mode: Tensor
```

Returns the mode of the distribution.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

[#](#api-tensorplay.distributions.CorrCholeskyTransform)

### CorrCholeskyTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.CorrCholeskyTransform.html)

```python
class tensorplay.distributions.CorrCholeskyTransform(cache_size: int = 0)
```

Transforms an unconstrained real vector $x$ with length $D*(D-1)/2$ into the
Cholesky factor of a D-dimension correlation matrix. This Cholesky factor is a lower
triangular matrix with positive diagonals and unit Euclidean norm for each row.
The transform is processed as follows:

- First we convert x into a lower triangular matrix in row order.

- For each row $X_i$ of the lower triangular part, we apply a signed version of class [StickBreakingTransform](/docs/generated/tensorplay.distributions.StickBreakingTransform.html#tensorplay.distributions.StickBreakingTransform) to transform $X_i$ into a unit Euclidean length vector using the following steps: - Scales into the interval $(-1, 1)$ domain: $r_i = \tanh(X_i)$. - Transforms into an unsigned domain: $z_i = r_i^2$. - Applies $s_i = StickBreakingTransform(z_i)$. - Transforms back into signed domain: $y_i = sign(r_i) * \sqrt{s_i}$.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
property sign: int
```

Returns the sign of the determinant of the Jacobian, if applicable.
In general this only makes sense for bijective transforms.

[#](#api-tensorplay.distributions.CumulativeDistributionTransform)

### CumulativeDistributionTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.CumulativeDistributionTransform.html)

```python
class tensorplay.distributions.CumulativeDistributionTransform(distribution: Distribution, cache_size: int = 0)
```

Transform via the cumulative distribution function of a probability distribution.

Parameters:

distribution ([Distribution](/docs/generated/tensorplay.distributions.Distribution.html#tensorplay.distributions.Distribution)) – Distribution whose cumulative distribution function to use for
the transformation.

Example:

```
# Construct a Gaussian copula from a multivariate normal.
base_dist = MultivariateNormal(
    loc=tensorplay.zeros(2),
    scale_tril=LKJCholesky(2).sample(),
)
transform = CumulativeDistributionTransform(Normal(0, 1))
copula = TransformedDistribution(base_dist, [transform])
```

```python
forward_shape(shape)
```

Infers the shape of the forward computation, given the input shape.
Defaults to preserving shape.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
inverse_shape(shape)
```

Infers the shapes of the inverse computation, given the output shape.
Defaults to preserving shape.

[#](#api-tensorplay.distributions.Dirichlet)

### Dirichlet

class[Full reference ↗](/docs/generated/tensorplay.distributions.Dirichlet.html)

```python
class tensorplay.distributions.Dirichlet(concentration: Tensor, validate_args: bool | None = None)
```

Creates a Dirichlet distribution parameterized by concentration concentration.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Dirichlet(tensorplay.tensor([0.5, 0.5]))
>>> m.sample()  # Dirichlet distributed with concentration [0.5, 0.5]
tensor([ 0.1046,  0.8954])
```

Parameters:

concentration ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – concentration parameter of the distribution
(often referred to as alpha)

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Distribution)

### Distribution

class[Full reference ↗](/docs/generated/tensorplay.distributions.Distribution.html)

```python
class tensorplay.distributions.Distribution(batch_shape: Size = (), event_shape: Size = (), validate_args: bool | None = None)
```

Distribution is the abstract base class for probability distributions.

Parameters:

- batch_shape ([tensorplay.Size](/docs/generated/tensorplay.Size.html#tensorplay.Size)) – The shape over which parameters are batched.

- event_shape ([tensorplay.Size](/docs/generated/tensorplay.Size.html#tensorplay.Size)) – The shape of a single sample (without batching).

- validate_args ([bool](https://docs.python.org/3/builtins/functions.html#bool), optional) – Whether to validate arguments. Default: None.

```python
property arg_constraints: dict[str, Constraint]
```

Returns a dictionary from argument names to
Constraint objects that
should be satisfied by each argument of this distribution. Args that
are not tensors need not appear in this dict.

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
entropy() → Tensor
```

Returns entropy of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
expand(batch_shape: Size | Sequence[int], _instance=None)
```

Returns a new distribution instance (or populates an existing instance
provided by a derived class) with batch dimensions expanded to
batch_shape. This method calls expand on
the distribution’s parameters. As such, this does not allocate new
memory for the expanded distribution instance. Additionally,
this does not repeat any args checking or parameter broadcasting in
__init__.py, when an instance is first created.

Parameters:

- batch_shape ([tensorplay.Size](/docs/generated/tensorplay.Size.html#tensorplay.Size)) – the desired expanded size.

- _instance – new instance provided by subclasses that need to override .expand.

Returns:

New distribution instance with batch dimensions expanded to
batch_shape.

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
log_prob(value: Tensor) → Tensor
```

Returns the log of the probability density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
property mean: Tensor
```

Returns the mean of the distribution.

```python
property mode: Tensor
```

Returns the mode of the distribution.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

```python
property support: Constraint | None
```

Returns a Constraint object
representing this distribution’s support.

```python
property variance: Tensor
```

Returns the variance of the distribution.

[#](#api-tensorplay.distributions.Exponential)

### Exponential

class[Full reference ↗](/docs/generated/tensorplay.distributions.Exponential.html)

```python
class tensorplay.distributions.Exponential(rate: Tensor | float, validate_args: bool | None = None)
```

Creates an Exponential distribution parameterized by rate.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Exponential(tensorplay.tensor([1.0]))
>>> m.sample()  # Exponential distributed with rate=1
tensor([ 0.1046])
```

Parameters:

rate ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – rate = 1 / scale of the distribution

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

[#](#api-tensorplay.distributions.ExponentialFamily)

### ExponentialFamily

class[Full reference ↗](/docs/generated/tensorplay.distributions.ExponentialFamily.html)

```python
class tensorplay.distributions.ExponentialFamily(batch_shape: Size = (), event_shape: Size = (), validate_args: bool | None = None)
```

ExponentialFamily is the abstract base class for probability distributions belonging to an
exponential family, whose probability mass/density function is defined below

$$p_{F}(x; \theta) = \exp(\langle t(x), \theta\rangle - F(\theta) + k(x))$$

where $\theta$ denotes the natural parameters, $t(x)$ denotes the sufficient statistic,
$F(\theta)$ is the log normalizer function for a given family and $k(x)$ is the carrier
measure.

> **Note**
>
> This class is an intermediary between the Distribution class and distributions which belong to an exponential family mainly to check the correctness of the .entropy() and analytic KL divergence methods. We use this class to compute the entropy and KL divergence using the AD framework and Bregman divergences (courtesy of: Frank Nielsen and Richard Nock, Entropies and Cross-entropies of Exponential Families).

```python
property arg_constraints: dict[str, Constraint]
```

Returns a dictionary from argument names to
Constraint objects that
should be satisfied by each argument of this distribution. Args that
are not tensors need not appear in this dict.

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
entropy()
```

Method to compute the entropy using Bregman divergence of the log normalizer.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
expand(batch_shape: Size | Sequence[int], _instance=None)
```

Returns a new distribution instance (or populates an existing instance
provided by a derived class) with batch dimensions expanded to
batch_shape. This method calls expand on
the distribution’s parameters. As such, this does not allocate new
memory for the expanded distribution instance. Additionally,
this does not repeat any args checking or parameter broadcasting in
__init__.py, when an instance is first created.

Parameters:

- batch_shape ([tensorplay.Size](/docs/generated/tensorplay.Size.html#tensorplay.Size)) – the desired expanded size.

- _instance – new instance provided by subclasses that need to override .expand.

Returns:

New distribution instance with batch dimensions expanded to
batch_shape.

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
log_prob(value: Tensor) → Tensor
```

Returns the log of the probability density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
property mean: Tensor
```

Returns the mean of the distribution.

```python
property mode: Tensor
```

Returns the mode of the distribution.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

```python
property support: Constraint | None
```

Returns a Constraint object
representing this distribution’s support.

```python
property variance: Tensor
```

Returns the variance of the distribution.

[#](#api-tensorplay.distributions.ExpTransform)

### ExpTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.ExpTransform.html)

```python
class tensorplay.distributions.ExpTransform(cache_size: int = 0)
```

Transform via the mapping $y = \exp(x)$.

```python
forward_shape(shape)
```

Infers the shape of the forward computation, given the input shape.
Defaults to preserving shape.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
inverse_shape(shape)
```

Infers the shapes of the inverse computation, given the output shape.
Defaults to preserving shape.

[#](#api-tensorplay.distributions.FisherSnedecor)

### FisherSnedecor

class[Full reference ↗](/docs/generated/tensorplay.distributions.FisherSnedecor.html)

```python
class tensorplay.distributions.FisherSnedecor(df1: Tensor | float, df2: Tensor | float, validate_args: bool | None = None)
```

Creates a Fisher-Snedecor distribution parameterized by df1 and df2.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = FisherSnedecor(tensorplay.tensor([1.0]), tensorplay.tensor([2.0]))
>>> m.sample()  # Fisher-Snedecor-distributed with df1=1 and df2=2
tensor([ 0.2453])
```

Parameters:

- df1 ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – degrees of freedom parameter 1

- df2 ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – degrees of freedom parameter 2

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
entropy() → Tensor
```

Returns entropy of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Gamma)

### Gamma

class[Full reference ↗](/docs/generated/tensorplay.distributions.Gamma.html)

```python
class tensorplay.distributions.Gamma(concentration: Tensor | float, rate: Tensor | float, validate_args: bool | None = None)
```

Creates a Gamma distribution parameterized by shape concentration and rate.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Gamma(tensorplay.tensor([1.0]), tensorplay.tensor([1.0]))
>>> m.sample()  # Gamma distributed with concentration=1 and rate=1
tensor([ 0.1046])
```

Parameters:

- concentration ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – shape parameter of the distribution (often referred to as alpha)

- rate ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – rate parameter of the distribution (often referred to as beta), rate = 1 / scale

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.GeneralizedPareto)

### GeneralizedPareto

class[Full reference ↗](/docs/generated/tensorplay.distributions.GeneralizedPareto.html)

```python
class tensorplay.distributions.GeneralizedPareto(loc, scale, concentration, validate_args=None)
```

Creates a Generalized Pareto distribution parameterized by loc, scale, and concentration.

The Generalized Pareto distribution is a family of continuous probability distributions on the real line.
Special cases include Exponential (when loc = 0, concentration = 0), Pareto (when concentration > 0,
loc = scale / concentration), and Uniform (when concentration = -1).

This distribution is often used to model the tails of other distributions. This implementation is based on the
implementation in TensorFlow Probability.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = GeneralizedPareto(tensorplay.tensor([0.1]), tensorplay.tensor([2.0]), tensorplay.tensor([0.4]))
>>> m.sample()  # sample from a Generalized Pareto distribution with loc=0.1, scale=2.0, and concentration=0.4
tensor([ 1.5623])
```

Parameters:

- loc ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – Location parameter of the distribution

- scale ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – Scale parameter of the distribution

- concentration ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – Concentration parameter of the distribution

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Geometric)

### Geometric

class[Full reference ↗](/docs/generated/tensorplay.distributions.Geometric.html)

```python
class tensorplay.distributions.Geometric(probs: Tensor | bool | int | float | None = None, logits: Tensor | bool | int | float | None = None, validate_args: bool | None = None)
```

Creates a Geometric distribution parameterized by probs,
where probs is the probability of success of Bernoulli trials.

$$P(X=k) = (1-p)^{k} p, k = 0, 1, ...$$

> **Note**
>
> tensorplay.distributions.geometric.Geometric() $(k+1)$-th trial is the first success hence draws samples in $\{0, 1, \ldots\}$, whereas tensorplay.Tensor.geometric_() k-th trial is the first success hence draws samples in $\{1, 2, \ldots\}$.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Geometric(tensorplay.tensor([0.3]))
>>> m.sample()  # underlying Bernoulli has 30% chance 1; 70% chance 0
tensor([ 2.])
```

Parameters:

- probs (Number, [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – the probability of sampling 1. Must be in range (0, 1]

- logits (Number, [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – the log-odds of sampling 1.

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Gumbel)

### Gumbel

class[Full reference ↗](/docs/generated/tensorplay.distributions.Gumbel.html)

```python
class tensorplay.distributions.Gumbel(loc: Tensor | float, scale: Tensor | float, validate_args: bool | None = None)
```

Samples from a Gumbel Distribution.

Examples:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Gumbel(tensorplay.tensor([1.0]), tensorplay.tensor([2.0]))
>>> m.sample()  # sample from Gumbel distribution with loc=1, scale=2
tensor([ 1.0124])
```

Parameters:

- loc ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – Location parameter of the distribution

- scale ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – Scale parameter of the distribution

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value)
```

Computes the cumulative distribution function by inverting the
transform(s) and computing the score of the base distribution.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value)
```

Computes the inverse cumulative distribution function using
transform(s) and computing the score of the base distribution.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched. Samples first from base distribution and applies
transform() for every transform in the list.

```python
sample(sample_shape=())
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched. Samples first from
base distribution and applies transform() for every transform in the
list.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

[#](#api-tensorplay.distributions.HalfCauchy)

### HalfCauchy

class[Full reference ↗](/docs/generated/tensorplay.distributions.HalfCauchy.html)

```python
class tensorplay.distributions.HalfCauchy(scale: Tensor | float, validate_args: bool | None = None)
```

Creates a half-Cauchy distribution parameterized by scale where:

```
X ~ Cauchy(0, scale)
Y = |X| ~ HalfCauchy(scale)
```

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = HalfCauchy(tensorplay.tensor([1.0]))
>>> m.sample()  # half-cauchy distributed with scale=1
tensor([ 2.3214])
```

Parameters:

scale ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – scale of the full Cauchy distribution

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched. Samples first from base distribution and applies
transform() for every transform in the list.

```python
sample(sample_shape=())
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched. Samples first from
base distribution and applies transform() for every transform in the
list.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.HalfNormal)

### HalfNormal

class[Full reference ↗](/docs/generated/tensorplay.distributions.HalfNormal.html)

```python
class tensorplay.distributions.HalfNormal(scale: Tensor | float, validate_args: bool | None = None)
```

Creates a half-normal distribution parameterized by scale where:

```
X ~ Normal(0, scale)
Y = |X| ~ HalfNormal(scale)
```

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = HalfNormal(tensorplay.tensor([1.0]))
>>> m.sample()  # half-normal distributed with scale=1
tensor([ 0.1046])
```

Parameters:

scale ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – scale of the full Normal distribution

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched. Samples first from base distribution and applies
transform() for every transform in the list.

```python
sample(sample_shape=())
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched. Samples first from
base distribution and applies transform() for every transform in the
list.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Independent)

### Independent

class[Full reference ↗](/docs/generated/tensorplay.distributions.Independent.html)

```python
class tensorplay.distributions.Independent(base_distribution: D, reinterpreted_batch_ndims: int, validate_args: bool | None = None)
```

Reinterprets some of the batch dims of a distribution as event dims.

This is mainly useful for changing the shape of the result of
log_prob(). For example to create a diagonal Normal distribution with
the same shape as a Multivariate Normal distribution (so they are
interchangeable), you can:

```
>>> from tensorplay.distributions.multivariate_normal import MultivariateNormal
>>> from tensorplay.distributions.normal import Normal
>>> loc = tensorplay.zeros(3)
>>> scale = tensorplay.ones(3)
>>> mvn = MultivariateNormal(loc, scale_tril=tensorplay.diag(scale))
>>> [mvn.batch_shape, mvn.event_shape]
[tensorplay.Size([]), tensorplay.Size([3])]
>>> normal = Normal(loc, scale)
>>> [normal.batch_shape, normal.event_shape]
[tensorplay.Size([3]), tensorplay.Size([])]
>>> diagn = Independent(normal, 1)
>>> [diagn.batch_shape, diagn.event_shape]
[tensorplay.Size([]), tensorplay.Size([3])]
```

Parameters:

- base_distribution ([tensorplay.distributions.distribution.Distribution](/docs/generated/tensorplay.distributions.Distribution.html#tensorplay.distributions.Distribution)) – a base distribution

- reinterpreted_batch_ndims ([int](https://docs.python.org/3/builtins/functions.html#int)) – the number of batch dims to reinterpret as event dims

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.IndependentTransform)

### IndependentTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.IndependentTransform.html)

```python
class tensorplay.distributions.IndependentTransform(base_transform: Transform, reinterpreted_batch_ndims: int, cache_size: int = 0)
```

Wrapper around another transform to treat
reinterpreted_batch_ndims-many extra of the right most dimensions as
dependent. This has no effect on the forward or backward transforms, but
does sum out reinterpreted_batch_ndims-many of the rightmost dimensions
in log_abs_det_jacobian().

Parameters:

- base_transform ([Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform)) – A base transform.

- reinterpreted_batch_ndims ([int](https://docs.python.org/3/builtins/functions.html#int)) – The number of extra rightmost dimensions to treat as dependent.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

[#](#api-tensorplay.distributions.InverseGamma)

### InverseGamma

class[Full reference ↗](/docs/generated/tensorplay.distributions.InverseGamma.html)

```python
class tensorplay.distributions.InverseGamma(concentration: Tensor | float, rate: Tensor | float, validate_args: bool | None = None)
```

Creates an inverse gamma distribution parameterized by concentration and rate
where:

```
X ~ Gamma(concentration, rate)
Y = 1 / X ~ InverseGamma(concentration, rate)
```

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = InverseGamma(tensorplay.tensor([2.0]), tensorplay.tensor([3.0]))
>>> m.sample()
tensor([ 1.2953])
```

Parameters:

- concentration ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – shape parameter of the distribution (often referred to as alpha)

- rate ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – rate = 1 / scale of the distribution (often referred to as beta)

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value)
```

Computes the cumulative distribution function by inverting the
transform(s) and computing the score of the base distribution.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value)
```

Computes the inverse cumulative distribution function using
transform(s) and computing the score of the base distribution.

```python
log_prob(value)
```

Scores the sample by inverting the transform(s) and computing the score
using the score of the base distribution and the log abs det jacobian.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched. Samples first from base distribution and applies
transform() for every transform in the list.

```python
sample(sample_shape=())
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched. Samples first from
base distribution and applies transform() for every transform in the
list.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Kumaraswamy)

### Kumaraswamy

class[Full reference ↗](/docs/generated/tensorplay.distributions.Kumaraswamy.html)

```python
class tensorplay.distributions.Kumaraswamy(concentration1: Tensor | float, concentration0: Tensor | float, validate_args: bool | None = None)
```

Samples from a Kumaraswamy distribution.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Kumaraswamy(tensorplay.tensor([1.0]), tensorplay.tensor([1.0]))
>>> m.sample()  # sample from a Kumaraswamy distribution with concentration alpha=1 and beta=1
tensor([ 0.1729])
```

Parameters:

- concentration1 ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – 1st concentration parameter of the distribution (often referred to as alpha)

- concentration0 ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – 2nd concentration parameter of the distribution (often referred to as beta)

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value)
```

Computes the cumulative distribution function by inverting the
transform(s) and computing the score of the base distribution.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value)
```

Computes the inverse cumulative distribution function using
transform(s) and computing the score of the base distribution.

```python
log_prob(value)
```

Scores the sample by inverting the transform(s) and computing the score
using the score of the base distribution and the log abs det jacobian.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched. Samples first from base distribution and applies
transform() for every transform in the list.

```python
sample(sample_shape=())
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched. Samples first from
base distribution and applies transform() for every transform in the
list.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Laplace)

### Laplace

class[Full reference ↗](/docs/generated/tensorplay.distributions.Laplace.html)

```python
class tensorplay.distributions.Laplace(loc: Tensor | float, scale: Tensor | float, validate_args: bool | None = None)
```

Creates a Laplace distribution parameterized by loc and scale.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Laplace(tensorplay.tensor([0.0]), tensorplay.tensor([1.0]))
>>> m.sample()  # Laplace distributed with loc=0, scale=1
tensor([ 0.1046])
```

Parameters:

- loc ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – mean of the distribution

- scale ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – scale of the distribution

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

[#](#api-tensorplay.distributions.LKJCholesky)

### LKJCholesky

class[Full reference ↗](/docs/generated/tensorplay.distributions.LKJCholesky.html)

```python
class tensorplay.distributions.LKJCholesky(dim: int, concentration: Tensor | float = 1.0, validate_args: bool | None = None)
```

LKJ distribution for lower Cholesky factor of correlation matrices.
The distribution is controlled by concentration parameter $\eta$
to make the probability of the correlation matrix $M$ generated from
a Cholesky factor proportional to $\det(M)^{\eta - 1}$. Because of that,
when concentration == 1, we have a uniform distribution over Cholesky
factors of correlation matrices:

```
L ~ LKJCholesky(dim, concentration)
X = L @ L' ~ LKJCorr(dim, concentration)
```

Note that this distribution samples the
Cholesky factor of correlation matrices and not the correlation matrices
themselves and thereby differs slightly from the derivations in [1] for
the LKJCorr distribution. For sampling, this uses the Onion method from
[1] Section 3.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> l = LKJCholesky(3, 0.5)
>>> l.sample()  # l @ l.T is a sample of a correlation 3x3 matrix
tensor([[ 1.0000,  0.0000,  0.0000],
        [ 0.3516,  0.9361,  0.0000],
        [-0.1899,  0.4748,  0.8593]])
```

Parameters:

- dimension (dim) – dimension of the matrices

- concentration ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – concentration/shape parameter of the distribution (often referred to as eta)

References

[1] Generating random correlation matrices based on vines and extended onion method (2009),
Daniel Lewandowski, Dorota Kurowicka, Harry Joe.
Journal of Multivariate Analysis. 100. 10.1016/j.jmva.2009.04.008

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
entropy() → Tensor
```

Returns entropy of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
property mean: Tensor
```

Returns the mean of the distribution.

```python
property mode: Tensor
```

Returns the mode of the distribution.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

```python
property variance: Tensor
```

Returns the variance of the distribution.

[#](#api-tensorplay.distributions.LogisticNormal)

### LogisticNormal

class[Full reference ↗](/docs/generated/tensorplay.distributions.LogisticNormal.html)

```python
class tensorplay.distributions.LogisticNormal(loc: Tensor | float, scale: Tensor | float, validate_args: bool | None = None)
```

Creates a logistic-normal distribution parameterized by loc and scale
that define the base Normal distribution transformed with the
StickBreakingTransform such that:

```
X ~ LogisticNormal(loc, scale)
Y = log(X / (1 - X.cumsum(-1)))[..., :-1] ~ Normal(loc, scale)
```

Parameters:

- loc ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – mean of the base distribution

- scale ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – standard deviation of the base distribution

Example:

```
>>> # logistic-normal distributed with mean=(0, 0, 0) and stddev=(1, 1, 1)
>>> # of the base Normal distribution
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = LogisticNormal(tensorplay.tensor([0.0] * 3), tensorplay.tensor([1.0] * 3))
>>> m.sample()
tensor([ 0.7653,  0.0341,  0.0579,  0.1427])
```

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value)
```

Computes the cumulative distribution function by inverting the
transform(s) and computing the score of the base distribution.

```python
entropy() → Tensor
```

Returns entropy of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value)
```

Computes the inverse cumulative distribution function using
transform(s) and computing the score of the base distribution.

```python
log_prob(value)
```

Scores the sample by inverting the transform(s) and computing the score
using the score of the base distribution and the log abs det jacobian.

```python
property mean: Tensor
```

Returns the mean of the distribution.

```python
property mode: Tensor
```

Returns the mode of the distribution.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched. Samples first from base distribution and applies
transform() for every transform in the list.

```python
sample(sample_shape=())
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched. Samples first from
base distribution and applies transform() for every transform in the
list.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

```python
property variance: Tensor
```

Returns the variance of the distribution.

[#](#api-tensorplay.distributions.LogNormal)

### LogNormal

class[Full reference ↗](/docs/generated/tensorplay.distributions.LogNormal.html)

```python
class tensorplay.distributions.LogNormal(loc: Tensor | float, scale: Tensor | float, validate_args: bool | None = None)
```

Creates a log-normal distribution parameterized by
loc and scale where:

```
X ~ Normal(loc, scale)
Y = exp(X) ~ LogNormal(loc, scale)
```

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = LogNormal(tensorplay.tensor([0.0]), tensorplay.tensor([1.0]))
>>> m.sample()  # log-normal distributed with mean=0 and stddev=1
tensor([ 0.1046])
```

Parameters:

- loc ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – mean of log of distribution

- scale ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – standard deviation of log of the distribution

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value)
```

Computes the cumulative distribution function by inverting the
transform(s) and computing the score of the base distribution.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value)
```

Computes the inverse cumulative distribution function using
transform(s) and computing the score of the base distribution.

```python
log_prob(value)
```

Scores the sample by inverting the transform(s) and computing the score
using the score of the base distribution and the log abs det jacobian.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched. Samples first from base distribution and applies
transform() for every transform in the list.

```python
sample(sample_shape=())
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched. Samples first from
base distribution and applies transform() for every transform in the
list.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.LowerCholeskyTransform)

### LowerCholeskyTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.LowerCholeskyTransform.html)

```python
class tensorplay.distributions.LowerCholeskyTransform(cache_size: int = 0)
```

Transform from unconstrained matrices to lower-triangular matrices with
nonnegative diagonal entries.

This is useful for parameterizing positive definite matrices in terms of
their Cholesky factorization.

```python
forward_shape(shape)
```

Infers the shape of the forward computation, given the input shape.
Defaults to preserving shape.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
inverse_shape(shape)
```

Infers the shapes of the inverse computation, given the output shape.
Defaults to preserving shape.

```python
log_abs_det_jacobian(x, y)
```

Computes the log det jacobian log |dy/dx| given input and output.

```python
property sign: int
```

Returns the sign of the determinant of the Jacobian, if applicable.
In general this only makes sense for bijective transforms.

[#](#api-tensorplay.distributions.LowRankMultivariateNormal)

### LowRankMultivariateNormal

class[Full reference ↗](/docs/generated/tensorplay.distributions.LowRankMultivariateNormal.html)

```python
class tensorplay.distributions.LowRankMultivariateNormal(loc: Tensor, cov_factor: Tensor, cov_diag: Tensor, validate_args: bool | None = None)
```

Creates a multivariate normal distribution with covariance matrix having a low-rank form
parameterized by cov_factor and cov_diag:

```
covariance_matrix = cov_factor @ cov_factor.T + cov_diag
```

Example

```
>>> # xdoctest: +REQUIRES(env:TENSORPLAY_DOCTEST_LAPACK)
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = LowRankMultivariateNormal(
...     tensorplay.zeros(2), tensorplay.tensor([[1.0], [0.0]]), tensorplay.ones(2)
... )
>>> m.sample()  # normally distributed with mean=`[0,0]`, cov_factor=`[[1],[0]]`, cov_diag=`[1,1]`
tensor([-0.2102, -0.5429])
```

Parameters:

- loc ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – mean of the distribution with shape batch_shape + event_shape

- cov_factor ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – factor part of low-rank form of covariance matrix with shape batch_shape + event_shape + (rank,)

- cov_diag ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – diagonal part of low-rank form of covariance matrix with shape batch_shape + event_shape

> **Note**
>
> The computation for determinant and inverse of covariance matrix is avoided when cov_factor.shape[1] @@TPBLOCK_36@@

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.MixtureSameFamily)

### MixtureSameFamily

class[Full reference ↗](/docs/generated/tensorplay.distributions.MixtureSameFamily.html)

```python
class tensorplay.distributions.MixtureSameFamily(mixture_distribution: Categorical, component_distribution: Distribution, validate_args: bool | None = None)
```

The MixtureSameFamily distribution implements a (batch of) mixture
distribution where all components are from different parameterizations of
the same distribution type. It is parameterized by a Categorical
“selecting distribution” (over k components) and a component
distribution, i.e., a Distribution with a rightmost batch shape
(equal to [k]) which indexes each (batch of) component.

Examples:

```
>>> # xdoctest: +SKIP("undefined vars")
>>> # Construct Gaussian Mixture Model in 1D consisting of 5 equally
>>> # weighted normal distributions
>>> mix = D.Categorical(tensorplay.ones(5,))
>>> comp = D.Normal(tensorplay.randn(5,), tensorplay.rand(5,))
>>> gmm = MixtureSameFamily(mix, comp)

>>> # Construct Gaussian Mixture Model in 2D consisting of 5 equally
>>> # weighted bivariate normal distributions
>>> mix = D.Categorical(tensorplay.ones(5,))
>>> comp = D.Independent(D.Normal(
...          tensorplay.randn(5,2), tensorplay.rand(5,2)), 1)
>>> gmm = MixtureSameFamily(mix, comp)

>>> # Construct a batch of 3 Gaussian Mixture Models in 2D each
>>> # consisting of 5 random weighted bivariate normal distributions
>>> mix = D.Categorical(tensorplay.rand(3,5))
>>> comp = D.Independent(D.Normal(
...         tensorplay.randn(3,5,2), tensorplay.rand(3,5,2)), 1)
>>> gmm = MixtureSameFamily(mix, comp)
```

Parameters:

- mixture_distribution – tensorplay.distributions.Categorical-like instance. Manages the probability of selecting components. The number of categories must match the rightmost batch dimension of the component_distribution. Must have either scalar batch_shape or batch_shape matching component_distribution.batch_shape[:-1]

- component_distribution – tensorplay.distributions.Distribution-like instance. Right-most batch dimension indexes component.

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
entropy() → Tensor
```

Returns entropy of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
property mode: Tensor
```

Returns the mode of the distribution.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Multinomial)

### Multinomial

class[Full reference ↗](/docs/generated/tensorplay.distributions.Multinomial.html)

```python
class tensorplay.distributions.Multinomial(total_count: int = 1, probs: Tensor | None = None, logits: Tensor | None = None, validate_args: bool | None = None)
```

Creates a Multinomial distribution parameterized by total_count and
either probs or logits (but not both). The innermost dimension of
probs indexes over categories. All other dimensions index over batches.

Note that total_count need not be specified if only log_prob() is
called (see example below)

> **Note**
>
> The probs argument must be non-negative, finite and have a non-zero sum, and it will be normalized to sum to 1 along the last dimension. probs will return this normalized value. The logits argument will be interpreted as unnormalized log probabilities and can therefore be any real number. It will likewise be normalized so that the resulting probabilities sum to 1 along the last dimension. logits will return this normalized value.

- sample() requires a single shared total_count for all parameters and samples.

- log_prob() allows different total_count for each parameter and sample.

Example:

```
>>> # xdoctest: +SKIP("FIXME: found invalid values")
>>> m = Multinomial(100, tensorplay.tensor([ 1., 1., 1., 1.]))
>>> x = m.sample()  # equal probability of 0, 1, 2, 3
tensor([ 21.,  24.,  30.,  25.])

>>> Multinomial(probs=tensorplay.tensor([1., 1., 1., 1.])).log_prob(x)
tensor([-4.1338])
```

Parameters:

- total_count ([int](https://docs.python.org/3/builtins/functions.html#int)) – number of trials

- probs ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – event probabilities

- logits ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – event log probabilities (unnormalized)

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
property mode: Tensor
```

Returns the mode of the distribution.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.MultivariateNormal)

### MultivariateNormal

class[Full reference ↗](/docs/generated/tensorplay.distributions.MultivariateNormal.html)

```python
class tensorplay.distributions.MultivariateNormal(loc: Tensor, covariance_matrix: Tensor | None = None, precision_matrix: Tensor | None = None, scale_tril: Tensor | None = None, validate_args: bool | None = None)
```

Creates a multivariate normal (also called Gaussian) distribution
parameterized by a mean vector and a covariance matrix.

The multivariate normal distribution can be parameterized either
in terms of a positive definite covariance matrix $\mathbf{\Sigma}$
or a positive definite precision matrix $\mathbf{\Sigma}^{-1}$
or a lower-triangular matrix $\mathbf{L}$ with positive-valued
diagonal entries, such that
$\mathbf{\Sigma} = \mathbf{L}\mathbf{L}^\top$. This triangular matrix
can be obtained via e.g. Cholesky decomposition of the covariance.

Example

```
>>> # xdoctest: +REQUIRES(env:TENSORPLAY_DOCTEST_LAPACK)
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = MultivariateNormal(tensorplay.zeros(2), tensorplay.eye(2))
>>> m.sample()  # normally distributed with mean=`[0,0]` and covariance_matrix=`I`
tensor([-0.2102, -0.5429])
```

Parameters:

- loc ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – mean of the distribution

- covariance_matrix ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – positive-definite covariance matrix

- precision_matrix ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – positive-definite precision matrix

- scale_tril ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – lower-triangular factor of covariance, with positive-valued diagonal

> **Note**
>
> Only one of covariance_matrix or precision_matrix or scale_tril can be specified. Using scale_tril will be more efficient: all computations internally are based on scale_tril. If covariance_matrix or precision_matrix is passed instead, it is only used to compute the corresponding lower triangular matrices using a Cholesky decomposition.

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.NegativeBinomial)

### NegativeBinomial

class[Full reference ↗](/docs/generated/tensorplay.distributions.NegativeBinomial.html)

```python
class tensorplay.distributions.NegativeBinomial(total_count: Tensor | float, probs: Tensor | None = None, logits: Tensor | None = None, validate_args: bool | None = None)
```

Creates a Negative Binomial distribution, i.e. distribution
of the number of successful independent and identical Bernoulli trials
before total_count failures are achieved. The probability
of success of each Bernoulli trial is probs.

Parameters:

- total_count ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – non-negative number of negative Bernoulli trials to stop, although the distribution is still valid for real valued count

- probs ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – Event probabilities of success in the half open interval [0, 1)

- logits ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – Event log-odds for probabilities of success

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
entropy() → Tensor
```

Returns entropy of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Normal)

### Normal

class[Full reference ↗](/docs/generated/tensorplay.distributions.Normal.html)

```python
class tensorplay.distributions.Normal(loc: Tensor | float, scale: Tensor | float, validate_args: bool | None = None)
```

Creates a normal (also called Gaussian) distribution parameterized by
loc and scale.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Normal(tensorplay.tensor([0.0]), tensorplay.tensor([1.0]))
>>> m.sample()  # normally distributed with loc=0 and scale=1
tensor([ 0.1046])
```

Parameters:

- loc ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – mean of the distribution (often referred to as mu)

- scale ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – standard deviation of the distribution (often referred to as sigma)

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

[#](#api-tensorplay.distributions.OneHotCategorical)

### OneHotCategorical

class[Full reference ↗](/docs/generated/tensorplay.distributions.OneHotCategorical.html)

```python
class tensorplay.distributions.OneHotCategorical(probs: Tensor | None = None, logits: Tensor | None = None, validate_args: bool | None = None)
```

Creates a one-hot categorical distribution parameterized by probs or
logits.

Samples are one-hot coded vectors of size probs.size(-1).

> **Note**
>
> The probs argument must be non-negative, finite and have a non-zero sum, and it will be normalized to sum to 1 along the last dimension. probs will return this normalized value. The logits argument will be interpreted as unnormalized log probabilities and can therefore be any real number. It will likewise be normalized so that the resulting probabilities sum to 1 along the last dimension. logits will return this normalized value.

See also: [tensorplay.distributions.Categorical()](/docs/generated/tensorplay.distributions.Categorical.html#tensorplay.distributions.Categorical) for specifications of
probs and logits.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = OneHotCategorical(tensorplay.tensor([ 0.25, 0.25, 0.25, 0.25 ]))
>>> m.sample()  # equal probability of 0, 1, 2, 3
tensor([ 0.,  0.,  0.,  1.])
```

Parameters:

- probs ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – event probabilities

- logits ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – event log probabilities (unnormalized)

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.OneHotCategoricalStraightThrough)

### OneHotCategoricalStraightThrough

class[Full reference ↗](/docs/generated/tensorplay.distributions.OneHotCategoricalStraightThrough.html)

```python
class tensorplay.distributions.OneHotCategoricalStraightThrough(probs: Tensor | None = None, logits: Tensor | None = None, validate_args: bool | None = None)
```

Creates a reparameterizable [OneHotCategorical](/docs/generated/tensorplay.distributions.OneHotCategorical.html#tensorplay.distributions.OneHotCategorical) distribution based on the straight-
through gradient estimator from [1].

[1] Estimating or Propagating Gradients Through Stochastic Neurons for Conditional Computation
(Bengio et al., 2013)

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Pareto)

### Pareto

class[Full reference ↗](/docs/generated/tensorplay.distributions.Pareto.html)

```python
class tensorplay.distributions.Pareto(scale: Tensor | float, alpha: Tensor | float, validate_args: bool | None = None)
```

Samples from a Pareto Type 1 distribution.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Pareto(tensorplay.tensor([1.0]), tensorplay.tensor([1.0]))
>>> m.sample()  # sample from a Pareto distribution with scale=1 and alpha=1
tensor([ 1.5623])
```

Parameters:

- scale ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – Scale parameter of the distribution

- alpha ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – Shape parameter of the distribution

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value)
```

Computes the cumulative distribution function by inverting the
transform(s) and computing the score of the base distribution.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value)
```

Computes the inverse cumulative distribution function using
transform(s) and computing the score of the base distribution.

```python
log_prob(value)
```

Scores the sample by inverting the transform(s) and computing the score
using the score of the base distribution and the log abs det jacobian.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched. Samples first from base distribution and applies
transform() for every transform in the list.

```python
sample(sample_shape=())
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched. Samples first from
base distribution and applies transform() for every transform in the
list.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Poisson)

### Poisson

class[Full reference ↗](/docs/generated/tensorplay.distributions.Poisson.html)

```python
class tensorplay.distributions.Poisson(rate: Tensor | bool | int | float, validate_args: bool | None = None)
```

Creates a Poisson distribution parameterized by rate, the rate parameter.

Samples are nonnegative integers, with a pmf given by

$$\mathrm{rate}^k \frac{e^{-\mathrm{rate}}}{k!}$$

Example:

```
>>> # xdoctest: +SKIP("poisson_cpu not implemented for 'Long'")
>>> m = Poisson(tensorplay.tensor([4]))
>>> m.sample()
tensor([ 3.])
```

Parameters:

rate (Number, [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – the rate parameter

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
entropy()
```

Method to compute the entropy using Bregman divergence of the log normalizer.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.PositiveDefiniteTransform)

### PositiveDefiniteTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.PositiveDefiniteTransform.html)

```python
class tensorplay.distributions.PositiveDefiniteTransform(cache_size: int = 0)
```

Transform from unconstrained matrices to positive-definite matrices.

```python
forward_shape(shape)
```

Infers the shape of the forward computation, given the input shape.
Defaults to preserving shape.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
inverse_shape(shape)
```

Infers the shapes of the inverse computation, given the output shape.
Defaults to preserving shape.

```python
log_abs_det_jacobian(x, y)
```

Computes the log det jacobian log |dy/dx| given input and output.

```python
property sign: int
```

Returns the sign of the determinant of the Jacobian, if applicable.
In general this only makes sense for bijective transforms.

[#](#api-tensorplay.distributions.PowerTransform)

### PowerTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.PowerTransform.html)

```python
class tensorplay.distributions.PowerTransform(exponent: Tensor, cache_size: int = 0)
```

Transform via the mapping $y = x^{\text{exponent}}$.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

[#](#api-tensorplay.distributions.RelaxedBernoulli)

### RelaxedBernoulli

class[Full reference ↗](/docs/generated/tensorplay.distributions.RelaxedBernoulli.html)

```python
class tensorplay.distributions.RelaxedBernoulli(temperature: Tensor, probs: Tensor | bool | int | float | None = None, logits: Tensor | bool | int | float | None = None, validate_args: bool | None = None)
```

Creates a RelaxedBernoulli distribution, parameterized by
temperature, and either probs or logits
(but not both). This is a relaxed version of the Bernoulli distribution,
so the values are in (0, 1), and has reparametrizable samples.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = RelaxedBernoulli(tensorplay.tensor([2.2]),
...                      tensorplay.tensor([0.1, 0.2, 0.3, 0.99]))
>>> m.sample()
tensor([ 0.2951,  0.3442,  0.8918,  0.9021])
```

Parameters:

- temperature ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – relaxation temperature

- probs (Number, [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – the probability of sampling 1

- logits (Number, [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – the log-odds of sampling 1

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value)
```

Computes the cumulative distribution function by inverting the
transform(s) and computing the score of the base distribution.

```python
entropy() → Tensor
```

Returns entropy of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value)
```

Computes the inverse cumulative distribution function using
transform(s) and computing the score of the base distribution.

```python
log_prob(value)
```

Scores the sample by inverting the transform(s) and computing the score
using the score of the base distribution and the log abs det jacobian.

```python
property mean: Tensor
```

Returns the mean of the distribution.

```python
property mode: Tensor
```

Returns the mode of the distribution.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched. Samples first from base distribution and applies
transform() for every transform in the list.

```python
sample(sample_shape=())
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched. Samples first from
base distribution and applies transform() for every transform in the
list.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

```python
property variance: Tensor
```

Returns the variance of the distribution.

[#](#api-tensorplay.distributions.RelaxedOneHotCategorical)

### RelaxedOneHotCategorical

class[Full reference ↗](/docs/generated/tensorplay.distributions.RelaxedOneHotCategorical.html)

```python
class tensorplay.distributions.RelaxedOneHotCategorical(temperature: Tensor, probs: Tensor | None = None, logits: Tensor | None = None, validate_args: bool | None = None)
```

Creates a RelaxedOneHotCategorical distribution parameterized by
temperature, and either probs or logits.
This is a relaxed version of the [OneHotCategorical](/docs/generated/tensorplay.distributions.OneHotCategorical.html#tensorplay.distributions.OneHotCategorical) distribution, so
its samples are on simplex, and are reparametrizable.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = RelaxedOneHotCategorical(tensorplay.tensor([2.2]),
...                              tensorplay.tensor([0.1, 0.2, 0.3, 0.4]))
>>> m.sample()
tensor([ 0.1294,  0.2324,  0.3859,  0.2523])
```

Parameters:

- temperature ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – relaxation temperature

- probs ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – event probabilities

- logits ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – unnormalized log probability for each event

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value)
```

Computes the cumulative distribution function by inverting the
transform(s) and computing the score of the base distribution.

```python
entropy() → Tensor
```

Returns entropy of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value)
```

Computes the inverse cumulative distribution function using
transform(s) and computing the score of the base distribution.

```python
log_prob(value)
```

Scores the sample by inverting the transform(s) and computing the score
using the score of the base distribution and the log abs det jacobian.

```python
property mean: Tensor
```

Returns the mean of the distribution.

```python
property mode: Tensor
```

Returns the mode of the distribution.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched. Samples first from base distribution and applies
transform() for every transform in the list.

```python
sample(sample_shape=())
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched. Samples first from
base distribution and applies transform() for every transform in the
list.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

```python
property variance: Tensor
```

Returns the variance of the distribution.

[#](#api-tensorplay.distributions.ReshapeTransform)

### ReshapeTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.ReshapeTransform.html)

```python
class tensorplay.distributions.ReshapeTransform(in_shape: Size, out_shape: Size, cache_size: int = 0)
```

Unit Jacobian transform to reshape the rightmost part of a tensor.

Note that in_shape and out_shape must have the same number of
elements, just as for tensorplay.Tensor.reshape().

Parameters:

- in_shape ([tensorplay.Size](/docs/generated/tensorplay.Size.html#tensorplay.Size)) – The input event shape.

- out_shape ([tensorplay.Size](/docs/generated/tensorplay.Size.html#tensorplay.Size)) – The output event shape.

- cache_size ([int](https://docs.python.org/3/builtins/functions.html#int)) – Size of cache. If zero, no caching is done. If one, the latest single value is cached. Only 0 and 1 are supported. (Default 0.)

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
property sign: int
```

Returns the sign of the determinant of the Jacobian, if applicable.
In general this only makes sense for bijective transforms.

[#](#api-tensorplay.distributions.SigmoidTransform)

### SigmoidTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.SigmoidTransform.html)

```python
class tensorplay.distributions.SigmoidTransform(cache_size: int = 0)
```

Transform via the mapping $y = \frac{1}{1 + \exp(-x)}$ and $x = \text{logit}(y)$.

```python
forward_shape(shape)
```

Infers the shape of the forward computation, given the input shape.
Defaults to preserving shape.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
inverse_shape(shape)
```

Infers the shapes of the inverse computation, given the output shape.
Defaults to preserving shape.

[#](#api-tensorplay.distributions.SoftmaxTransform)

### SoftmaxTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.SoftmaxTransform.html)

```python
class tensorplay.distributions.SoftmaxTransform(cache_size: int = 0)
```

Transform from unconstrained space to the simplex via $y = \exp(x)$ then
normalizing.

This is not bijective and cannot be used for HMC. However this acts mostly
coordinate-wise (except for the final normalization), and thus is
appropriate for coordinate-wise optimization algorithms.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
log_abs_det_jacobian(x, y)
```

Computes the log det jacobian log |dy/dx| given input and output.

```python
property sign: int
```

Returns the sign of the determinant of the Jacobian, if applicable.
In general this only makes sense for bijective transforms.

[#](#api-tensorplay.distributions.SoftplusTransform)

### SoftplusTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.SoftplusTransform.html)

```python
class tensorplay.distributions.SoftplusTransform(cache_size: int = 0)
```

Transform via the mapping $\text{Softplus}(x) = \log(1 + \exp(x))$.
The implementation reverts to the linear function when $x > 20$.

```python
forward_shape(shape)
```

Infers the shape of the forward computation, given the input shape.
Defaults to preserving shape.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
inverse_shape(shape)
```

Infers the shapes of the inverse computation, given the output shape.
Defaults to preserving shape.

[#](#api-tensorplay.distributions.StackTransform)

### StackTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.StackTransform.html)

```python
class tensorplay.distributions.StackTransform(tseq: Sequence[Transform], dim: int = 0, cache_size: int = 0)
```

Transform functor that applies a sequence of transforms tseq
component-wise to each submatrix at dim
in a way compatible with tensorplay.stack().

Example:

```
x = tensorplay.stack([tensorplay.range(1, 10), tensorplay.range(1, 10)], dim=1)
t = StackTransform([ExpTransform(), identity_transform], dim=1)
y = t(x)
```

```python
forward_shape(shape)
```

Infers the shape of the forward computation, given the input shape.
Defaults to preserving shape.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
inverse_shape(shape)
```

Infers the shapes of the inverse computation, given the output shape.
Defaults to preserving shape.

```python
property sign: int
```

Returns the sign of the determinant of the Jacobian, if applicable.
In general this only makes sense for bijective transforms.

[#](#api-tensorplay.distributions.StickBreakingTransform)

### StickBreakingTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.StickBreakingTransform.html)

```python
class tensorplay.distributions.StickBreakingTransform(cache_size: int = 0)
```

Transform from unconstrained space to the simplex of one additional
dimension via a stick-breaking process.

This transform arises as an iterated sigmoid transform in a stick-breaking
construction of the Dirichlet distribution: the first logit is
transformed via sigmoid to the first probability and the probability of
everything else, and then the process recurses.

This is bijective and appropriate for use in HMC; however it mixes
coordinates together and is less appropriate for optimization.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
property sign: int
```

Returns the sign of the determinant of the Jacobian, if applicable.
In general this only makes sense for bijective transforms.

[#](#api-tensorplay.distributions.StudentT)

### StudentT

class[Full reference ↗](/docs/generated/tensorplay.distributions.StudentT.html)

```python
class tensorplay.distributions.StudentT(df: Tensor | float, loc: Tensor | float = 0.0, scale: Tensor | float = 1.0, validate_args: bool | None = None)
```

Creates a Student’s t-distribution parameterized by degree of
freedom df, mean loc and scale scale.

Example:

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = StudentT(tensorplay.tensor([2.0]))
>>> m.sample()  # Student's t-distributed with degrees of freedom=2
tensor([ 0.1046])
```

Parameters:

- df ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – degrees of freedom

- loc ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – mean of the distribution

- scale ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – scale of the distribution

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.TanhTransform)

### TanhTransform

class[Full reference ↗](/docs/generated/tensorplay.distributions.TanhTransform.html)

```python
class tensorplay.distributions.TanhTransform(cache_size: int = 0)
```

Transform via the mapping $y = \tanh(x)$.

It is equivalent to

```
ComposeTransform(
    [
        AffineTransform(0.0, 2.0),
        SigmoidTransform(),
        AffineTransform(-1.0, 2.0),
    ]
)
```

However this might not be numerically stable, thus it is recommended to use TanhTransform
instead.

Note that one should use cache_size=1 when it comes to NaN/Inf values.

```python
forward_shape(shape)
```

Infers the shape of the forward computation, given the input shape.
Defaults to preserving shape.

```python
property inv: Transform
```

Returns the inverse [Transform](/docs/generated/tensorplay.distributions.Transform.html#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
inverse_shape(shape)
```

Infers the shapes of the inverse computation, given the output shape.
Defaults to preserving shape.

[#](#api-tensorplay.distributions.Transform)

### Transform

class[Full reference ↗](/docs/generated/tensorplay.distributions.Transform.html)

```python
class tensorplay.distributions.Transform(cache_size: int = 0)
```

Abstract class for invertible transformations with computable log
det jacobians. They are primarily used in
[tensorplay.distributions.TransformedDistribution](/docs/generated/tensorplay.distributions.TransformedDistribution.html#tensorplay.distributions.TransformedDistribution).

Caching is useful for transforms whose inverses are either expensive or
numerically unstable. Note that care must be taken with memoized values
since the autograd graph may be reversed. For example while the following
works with or without caching:

```
y = t(x)
t.log_abs_det_jacobian(x, y).backward()  # x will receive gradients.
```

However the following will error when caching due to dependency reversal:

```
y = t(x)
z = t.inv(y)
grad(z.sum(), [y])  # error because z is x
```

Derived classes should implement one or both of _call() or
_inverse(). Derived classes that set bijective=True should also
implement [log_abs_det_jacobian()](#tensorplay.distributions.Transform.log_abs_det_jacobian).

Parameters:

cache_size ([int](https://docs.python.org/3/builtins/functions.html#int)) – Size of cache. If zero, no caching is done. If one,
the latest single value is cached. Only 0 and 1 are supported.

Variables:

- domain (Constraint) – The constraint representing valid inputs to this transform.

- codomain (Constraint) – The constraint representing valid outputs to this transform which are inputs to the inverse transform.

- bijective ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether this transform is bijective. A transform t is bijective iff t.inv(t(x)) == x and t(t.inv(y)) == y for every x in the domain and y in the codomain. Transforms that are not bijective should at least maintain the weaker pseudoinverse properties t(t.inv(t(x)) == t(x) and t.inv(t(t.inv(y))) == t.inv(y).

- sign ([int](https://docs.python.org/3/builtins/functions.html#int) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – For bijective univariate transforms, this should be +1 or -1 depending on whether transform is monotone increasing or decreasing.

```python
forward_shape(shape)
```

Infers the shape of the forward computation, given the input shape.
Defaults to preserving shape.

```python
property inv: Transform
```

Returns the inverse [Transform](#tensorplay.distributions.Transform) of this transform.
This should satisfy t.inv.inv is t.

```python
inverse_shape(shape)
```

Infers the shapes of the inverse computation, given the output shape.
Defaults to preserving shape.

```python
log_abs_det_jacobian(x, y)
```

Computes the log det jacobian log |dy/dx| given input and output.

```python
property sign: int
```

Returns the sign of the determinant of the Jacobian, if applicable.
In general this only makes sense for bijective transforms.

[#](#api-tensorplay.distributions.TransformedDistribution)

### TransformedDistribution

class[Full reference ↗](/docs/generated/tensorplay.distributions.TransformedDistribution.html)

```python
class tensorplay.distributions.TransformedDistribution(base_distribution: Distribution, transforms: Transform | list[Transform], validate_args: bool | None = None)
```

Extension of the Distribution class, which applies a sequence of Transforms
to a base distribution.  Let f be the composition of transforms applied:

```
X ~ BaseDistribution
Y = f(X) ~ TransformedDistribution(BaseDistribution, f)
log p(Y) = log p(X) + log |det (dX/dY)|
```

Note that the .event_shape of a [TransformedDistribution](#tensorplay.distributions.TransformedDistribution) is the
maximum shape of its base distribution and its transforms, since transforms
can introduce correlations among events.

An example for the usage of [TransformedDistribution](#tensorplay.distributions.TransformedDistribution) would be:

```
# Building a Logistic Distribution
# X ~ Uniform(0, 1)
# f = a + b * logit(X)
# Y ~ f(X) ~ Logistic(a, b)
base_distribution = Uniform(0, 1)
transforms = [SigmoidTransform().inv, AffineTransform(loc=a, scale=b)]
logistic = TransformedDistribution(base_distribution, transforms)
```

For more examples, please look at the implementations of
[Gumbel](/docs/generated/tensorplay.distributions.Gumbel.html#tensorplay.distributions.Gumbel),
[HalfCauchy](/docs/generated/tensorplay.distributions.HalfCauchy.html#tensorplay.distributions.HalfCauchy),
[HalfNormal](/docs/generated/tensorplay.distributions.HalfNormal.html#tensorplay.distributions.HalfNormal),
[LogNormal](/docs/generated/tensorplay.distributions.LogNormal.html#tensorplay.distributions.LogNormal),
[Pareto](/docs/generated/tensorplay.distributions.Pareto.html#tensorplay.distributions.Pareto),
[Weibull](/docs/generated/tensorplay.distributions.Weibull.html#tensorplay.distributions.Weibull),
[RelaxedBernoulli](/docs/generated/tensorplay.distributions.RelaxedBernoulli.html#tensorplay.distributions.RelaxedBernoulli) and
[RelaxedOneHotCategorical](/docs/generated/tensorplay.distributions.RelaxedOneHotCategorical.html#tensorplay.distributions.RelaxedOneHotCategorical)

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value)
```

Computes the cumulative distribution function by inverting the
transform(s) and computing the score of the base distribution.

```python
entropy() → Tensor
```

Returns entropy of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value)
```

Computes the inverse cumulative distribution function using
transform(s) and computing the score of the base distribution.

```python
log_prob(value)
```

Scores the sample by inverting the transform(s) and computing the score
using the score of the base distribution and the log abs det jacobian.

```python
property mean: Tensor
```

Returns the mean of the distribution.

```python
property mode: Tensor
```

Returns the mode of the distribution.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched. Samples first from base distribution and applies
transform() for every transform in the list.

```python
sample(sample_shape=())
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched. Samples first from
base distribution and applies transform() for every transform in the
list.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

```python
property variance: Tensor
```

Returns the variance of the distribution.

[#](#api-tensorplay.distributions.Uniform)

### Uniform

class[Full reference ↗](/docs/generated/tensorplay.distributions.Uniform.html)

```python
class tensorplay.distributions.Uniform(low: Tensor | float, high: Tensor | float, validate_args: bool | None = None)
```

Generates uniformly distributed random samples from the half-open interval
[low, high).

Example:

```
>>> m = Uniform(tensorplay.tensor([0.0]), tensorplay.tensor([5.0]))
>>> m.sample()  # uniformly distributed in the range [0.0, 5.0)
>>> # xdoctest: +SKIP
tensor([ 2.3418])
```

Parameters:

- low ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – lower range (inclusive).

- high ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – upper range (exclusive).

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

[#](#api-tensorplay.distributions.VonMises)

### VonMises

class[Full reference ↗](/docs/generated/tensorplay.distributions.VonMises.html)

```python
class tensorplay.distributions.VonMises(loc: Tensor, concentration: Tensor, validate_args: bool | None = None)
```

A circular von Mises distribution.

This implementation uses polar coordinates. The loc and value args
can be any real number (to facilitate unconstrained optimization), but are
interpreted as angles modulo 2 pi.

Example::

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = VonMises(tensorplay.tensor([1.0]), tensorplay.tensor([1.0]))
>>> m.sample()  # von Mises distributed with loc=1 and concentration=1
tensor([1.9777])
```

Parameters:

- loc ([tensorplay.Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – an angle in radians.

- concentration ([tensorplay.Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – concentration parameter

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
entropy() → Tensor
```

Returns entropy of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
property mean: Tensor
```

The provided mean is the circular one.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched.

```python
sample(sample_shape=())
```

The sampling algorithm for the von Mises distribution is based on the
following paper: D.J. Best and N.I. Fisher, “Efficient simulation of the
von Mises distribution.” Applied Statistics (1979): 152-157.

Sampling is always done in double precision internally to avoid a hang
in _rejection_sample() for small values of the concentration, which
starts to happen for single precision around 1e-4 (see issue #88443).

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

```python
property variance: Tensor
```

The provided variance is the circular one.

[#](#api-tensorplay.distributions.Weibull)

### Weibull

class[Full reference ↗](/docs/generated/tensorplay.distributions.Weibull.html)

```python
class tensorplay.distributions.Weibull(scale: Tensor | float, concentration: Tensor | float, validate_args: bool | None = None)
```

Samples from a two-parameter Weibull distribution.

Example

```
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> m = Weibull(tensorplay.tensor([1.0]), tensorplay.tensor([1.0]))
>>> m.sample()  # sample from a Weibull distribution with scale=1, concentration=1
tensor([ 0.4784])
```

Parameters:

- scale ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – Scale parameter of distribution (lambda).

- concentration ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – Concentration parameter of distribution (k/shape).

- validate_args ([bool](https://docs.python.org/3/builtins/functions.html#bool), optional) – Whether to validate arguments. Default: None.

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value)
```

Computes the cumulative distribution function by inverting the
transform(s) and computing the score of the base distribution.

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value)
```

Computes the inverse cumulative distribution function using
transform(s) and computing the score of the base distribution.

```python
log_prob(value)
```

Scores the sample by inverting the transform(s) and computing the score
using the score of the base distribution and the log abs det jacobian.

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped reparameterized sample or sample_shape
shaped batch of reparameterized samples if the distribution parameters
are batched. Samples first from base distribution and applies
transform() for every transform in the list.

```python
sample(sample_shape=())
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched. Samples first from
base distribution and applies transform() for every transform in the
list.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.

[#](#api-tensorplay.distributions.Wishart)

### Wishart

class[Full reference ↗](/docs/generated/tensorplay.distributions.Wishart.html)

```python
class tensorplay.distributions.Wishart(df: Tensor | bool | int | float, covariance_matrix: Tensor | None = None, precision_matrix: Tensor | None = None, scale_tril: Tensor | None = None, validate_args: bool | None = None)
```

Creates a Wishart distribution parameterized by a symmetric positive definite matrix $\Sigma$,
or its Cholesky decomposition $\mathbf{\Sigma} = \mathbf{L}\mathbf{L}^\top$

Example

```
>>> # xdoctest: +SKIP("FIXME: scale_tril must be at least two-dimensional")
>>> m = Wishart(tensorplay.Tensor([2]), covariance_matrix=tensorplay.eye(2))
>>> m.sample()  # Wishart distributed with mean=`df * I` and
>>> # variance(x_ij)=`df` for i != j and variance(x_ij)=`2 * df` for i == j
```

Parameters:

- df ([float](https://docs.python.org/3/builtins/functions.html#float) or [Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – real-valued parameter larger than the (dimension of Square matrix) - 1

- covariance_matrix ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – positive-definite covariance matrix

- precision_matrix ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – positive-definite precision matrix

- scale_tril ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor)) – lower-triangular factor of covariance, with positive-valued diagonal

> **Note**
>
> Only one of covariance_matrix or precision_matrix or scale_tril can be specified. Using scale_tril will be more efficient: all computations internally are based on scale_tril. If covariance_matrix or precision_matrix is passed instead, it is only used to compute the corresponding lower triangular matrices using a Cholesky decomposition. ‘tensorplay.distributions.LKJCholesky’ is a restricted Wishart distribution.[1]

References

[1] Wang, Z., Wu, Y. and Chu, H., 2018. On equivalence of the LKJ distribution and the restricted Wishart distribution.
[2] Sawyer, S., 2007. Wishart Distributions and Inverse-Wishart Sampling.
[3] Anderson, T. W., 2003. An Introduction to Multivariate Statistical Analysis (3rd ed.).
[4] Odell, P. L. & Feiveson, A. H., 1966. A Numerical Procedure to Generate a Sample Covariance Matrix. JASA, 61(313):199-203.
[5] Ku, Y.-C. & Bloomfield, P., 2010. Generating Random Wishart Matrices with Fractional Degrees of Freedom in OX.

```python
property batch_shape: Size
```

Returns the shape over which parameters are batched.

```python
cdf(value: Tensor) → Tensor
```

Returns the cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
enumerate_support(expand: bool = True) → Tensor
```

Returns tensor containing all values supported by a discrete
distribution. The result will enumerate over dimension 0, so the shape
of the result will be (cardinality,) + batch_shape + event_shape
(where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step
[[0, 0], [1, 1], …]. With expand=False, enumeration happens
along dim 0, but with the remaining batch dimensions being
singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use
itertools.product(m.enumerate_support()).

Parameters:

expand ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – whether to expand the support over the
batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

```python
property event_shape: Size
```

Returns the shape of a single sample (without batching).

```python
icdf(value: Tensor) → Tensor
```

Returns the inverse cumulative density/mass function evaluated at
value.

Parameters:

value ([Tensor](/docs/generated/tensorplay.Tensor.html#tensorplay.Tensor))

```python
perplexity() → Tensor
```

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

```python
rsample(sample_shape: Size | Sequence[int] = (), max_try_correction=None) → Tensor
```

> **Warning**
>
> In some cases, sampling algorithm based on Bartlett decomposition may return singular matrix samples. Several tries to correct singular samples are performed by default, but it may end up returning singular matrix samples. Singular samples may return -inf values in .log_prob(). In those cases, the user should validate the samples and either fix the value of df or adjust max_try_correction value for argument in .rsample accordingly.

```python
sample(sample_shape: Size | Sequence[int] = ()) → Tensor
```

Generates a sample_shape shaped sample or sample_shape shaped batch of
samples if the distribution parameters are batched.

```python
sample_n(n: int) → Tensor
```

Generates n samples or n batches of samples if the distribution
parameters are batched.

```python
static set_default_validate_args(value: bool) → None
```

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation
is on by default, but is disabled if Python is run in optimized mode
(via python -O). Validation may be expensive, so you may want to
disable it once a model is working.

Parameters:

value ([bool](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to enable validation.

```python
property stddev: Tensor
```

Returns the standard deviation of the distribution.