MultivariateNormal

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)[source]

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) – mean of the distribution

• covariance_matrix (Tensor) – positive-definite covariance matrix

• precision_matrix (Tensor) – positive-definite precision matrix

• scale_tril (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.

property batch_shape: Size

Returns the shape over which parameters are batched.

cdf(value: Tensor) → Tensor

Returns the cumulative density/mass function evaluated at value.

Parameters:

value (Tensor)

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) – whether to expand the support over the batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

property event_shape: Size

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

icdf(value: Tensor) → Tensor

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

Parameters:

value (Tensor)

perplexity() → Tensor

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

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.

sample_n(n: int) → Tensor

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

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) – Whether to enable validation.

property stddev: Tensor

Returns the standard deviation of the distribution.