Lucid3.0
class

CorrCholeskyTransform

extendsTransform
CorrCholeskyTransform(dim: int)
source

Bijection from Rd(d−1)/2\mathbb{R}^{d(d-1)/2} to Cholesky factors of correlation matrices.

Maps an unconstrained vector of length d(d−1)/2d(d-1)/2 to the lower-triangular Cholesky factor LL of a d×dd \times d correlation matrix (so LL⊤L L^\top is positive-definite with unit diagonal). This is the standard reparameterisation used by Stan, by Lewandowski–Kurowicka–Joe (LKJ) priors, and by the reference framework's correlation-matrix flow. event_dim = 2.

The construction applies tanh to the free parameters, treats each resulting value as a partial correlation, then normalises each row of the lower triangle so the rows of LL have unit 2-norm (which forces LL⊤L L^\top to have unit diagonal).

Parameters

dimint
Size d≥2d \geq 2 of the square correlation matrix. The unconstrained input has trailing dimension d(d−1)/2d(d-1)/2.

Notes

Forward (row-by-row stick-breaking on the unit sphere):

zij=tanh⁡(xij),Lij=zij1−∑k<jLik2    (i>j),Lii=1−∑k<iLik2z_{ij} = \tanh(x_{ij}), \qquad L_{ij} = z_{ij}\sqrt{1 - \sum_{k < j} L_{ik}^2}\;\;(i > j), \qquad L_{ii} = \sqrt{1 - \sum_{k < i} L_{ik}^2}

Inverse:

zij=Lij1−∑k<jLik2,xij=arctanh(zij)z_{ij} = \frac{L_{ij}}{\sqrt{1 - \sum_{k < j} L_{ik}^2}}, \qquad x_{ij} = \mathrm{arctanh}(z_{ij})

Log Jacobian determinant (closed form from Lewandowski et al., 2009):

log⁡∣det⁡J∣=∑i>jlog⁡(1−tanh⁡2(xij))+∑i=1d−1(d−i)log⁡Lii\log|\det J| = \sum_{i>j} \log(1 - \tanh^2(x_{ij})) + \sum_{i=1}^{d-1} (d - i)\log L_{ii}

Combine with the lucid.distributions.relaxed.LKJCholesky distribution (or equivalent) to learn unconstrained correlation matrices end-to-end.

Examples

>>> import lucid
>>> from lucid.distributions.transforms import CorrCholeskyTransform
>>> T = CorrCholeskyTransform(dim=3)
>>> x = lucid.zeros(3)  # d*(d-1)/2 = 3 free params
>>> L = T(x)  # 3x3 lower-triangular Cholesky of identity

Methods (2)

dunder

__init__

→None
__init__(dim: int)
source

Store the correlation-matrix dimension dim (must be >= 2).

fn

log_abs_det_jacobian

→Tensor
log_abs_det_jacobian(x: Tensor, y: Tensor)
source

Log-Jacobian of the unconstrained-to-Cholesky correlation map.

Combines the tanh contribution ∑i>jlog⁡(1−tanh⁡2(xij))\sum_{i>j} \log(1 - \tanh^2(x_{ij})) with the closed-form Lewandowski normalisation terms expressed directly from the output diagonal entries of y.