class

Wishart

extendsDistribution

Wishart(df: Tensor | float, covariance_matrix: Tensor | None = None, precision_matrix: Tensor | None = None, scale_tril: Tensor | None = None, validate_args: bool | None = None)

source

Wishart distribution over symmetric positive-definite matrices.

Matrix-variate generalisation of the lucid.distributions.Chi2 / Gamma distribution: the distribution of the (unnormalised) sample covariance matrix $S = \sum_{i=1}^{\nu} \mathbf{z}_i \mathbf{z}_i^\top$ formed from $\nu$ independent Multivariate Normal draws $\mathbf{z}_i \sim \mathcal{N}(\mathbf{0}, \Sigma)$ . It is the conjugate prior of the precision matrix of a Multivariate Normal with known mean.

Specify exactly one of covariance_matrix, precision_matrix, or scale_tril — the other parameterisations are derived internally via Cholesky factorisation.

Parameters

dfTensor or float

Degrees of freedom

\nu > D - 1

where

D

is the matrix dimension. Values

\nu \leq D - 1

violate the positive-definiteness guarantee.

covariance_matrixTensor= None

Positive-definite scale matrix

\Sigma

of shape (..., D, D).

precision_matrixTensor= None

Positive-definite precision matrix

\Sigma^{-1}

of shape (..., D, D).

scale_trilTensor= None

Lower-triangular Cholesky factor

L

\Sigma

(so

\Sigma = L L^\top

), shape (..., D, D) with positive diagonal.

validate_argsbool= None

If True, validate parameter constraints at construction time.

Notes

Probability density on the cone of symmetric positive-definite $D \times D$ matrices:

p(\mathbf{X}; \nu, \Sigma) = \frac{|\mathbf{X}|^{(\nu - D - 1)/2} \exp\!\bigl(-\tfrac{1}{2}\,\mathrm{tr}(\Sigma^{-1}\mathbf{X})\bigr)} {2^{\nu D / 2} |\Sigma|^{\nu/2} \Gamma_D(\nu/2)}

where $\Gamma_D$ is the multivariate gamma function:

\Gamma_D(a) = \pi^{D(D-1)/4} \prod_{i=1}^{D} \Gamma\!\left(a + \tfrac{1 - i}{2}\right)

Moments:

\mathbb{E}[\mathbf{X}] = \nu \Sigma, \qquad \mathrm{Var}[X_{ij}] = \nu (\Sigma_{ij}^2 + \Sigma_{ii} \Sigma_{jj})

Special cases / relations:

$D = 1$ → $\mathrm{Wishart}(\nu, \sigma^2) = \sigma^2 \chi^2(\nu)$ .
Inverse: if $\mathbf{X} \sim \mathrm{Wishart}(\nu, \Sigma)$ then $\mathbf{X}^{-1}$ follows the inverse-Wishart distribution, the conjugate prior of the covariance (not precision) matrix.
Bartlett decomposition: $\mathbf{X} = L A A^\top L^\top$ with $A$ lower-triangular containing $\chi^2$ draws on the diagonal and standard Normals below — used for sampling.

Examples

>>> import lucid
>>> from lucid.distributions import Wishart
>>> Sigma = lucid.tensor([[2.0, 0.5], [0.5, 1.0]])
>>> d = Wishart(df=5.0, covariance_matrix=Sigma)
>>> d.sample((4,))
Tensor([...])

Methods (6)

dunder

init

→None

__init__(df: Tensor | float, covariance_matrix: Tensor | None = None, precision_matrix: Tensor | None = None, scale_tril: Tensor | None = None, validate_args: bool | None = None)

source

Initialise a Wishart distribution.

Converts covariance_matrix or precision_matrix to a Cholesky factor internally. Exactly one scale specification must be provided.

Parameters

dfTensor | float

Degrees of freedom

\nu > D - 1

where

D

is the matrix dimension. Values

\nu \leq D - 1

violate the positive-definiteness guarantee.

covariance_matrixTensor | None= None

Positive-definite scale matrix

\Sigma

of shape (..., D, D).

precision_matrixTensor | None= None

Positive-definite precision matrix

\Sigma^{-1}

of shape (..., D, D). Converted via

\Sigma = (\Sigma^{-1})^{-1}

scale_trilTensor | None= None

Lower-triangular Cholesky factor

L

\Sigma

, shape (..., D, D) with positive diagonal.

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

prop

support

→Constraint

support: Constraint

source

Constraint: positive-definite symmetric matrices.

prop

mean

→Tensor

mean: Tensor

source

df · Σ.

prop

variance

→Tensor

variance: Tensor

source

Var[W_{ij}] = df · (Σ_{ij}² + Σ_{ii} Σ_{jj}).

sample

→Tensor

sample(sample_shape: tuple[int, ...] = ())

source

Draw a sample via the Bartlett decomposition.

Each sample is L A Aᵀ Lᵀ where L = scale_tril and A is a random lower-triangular matrix with:

diagonal A_{ii} ~ sqrt(χ²_{df − i}) for i = 0, …, d−1,
off-diagonal A_{ij} ~ N(0, 1) for i > j.

log_prob

→Tensor

log_prob(value: Tensor)

source

Log-density of the Wishart distribution.

.. code::

log p(X) = (df − d − 1)/2 · log|X| − tr(Σ⁻¹ X) / 2 − df · d / 2 · log 2 − df/2 · log|Σ| − log Γ_d(df/2)

where Γ_d is the multivariate gamma function.