covmats.CovViaPrecisionCholesky

class covmats.CovViaPrecisionCholesky(*args, **kwargs)

Representation of a covariance via the Cholesky factorization of its inverse (aka the precision matrix).

Notes

Let the covariance matrix be \(A\), its precision matrix be \(P = A^{-1}\), and \(L\) be the lower Cholesky factor such that \(L L^T = P\). Whitening of a data point \(x\) is performed by computing \(x^T L\). \(\log\det{A}\) is calculated as \(-2tr(\log{L})\), where the \(\log\) operation is performed element-wise.

This Covariance class does not support singular covariance matrices because the precision matrix does not exist for a singular covariance matrix.

Examples

Prepare a symmetric positive definite precision matrix P and a data point x. (If the precision matrix is not already available, consider the other factory methods of the Covariance class.)

>>> import numpy as np
>>> import covmats
>>> rng = np.random.default_rng()
>>> n = 5
>>> P = rng.random(size=(n, n))
>>> P = P @ P.T  # a precision matrix must be positive definite
>>> x = rng.random(size=n)

Create the Covariance object.

>>> cov = covmats.CovViaPrecisionCholesky(np.linalg.cholesky(P))

Compare the functionality of the Covariance object against reference implementations.

>>> res = cov.whiten(x)
>>> ref = x @ np.linalg.cholesky(P)
>>> np.allclose(res, ref)
True
>>> res = cov.log_pdet
>>> ref = -np.linalg.slogdet(P)[-1]
>>> np.allclose(res, ref)
True

__init__(L: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], precision: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None) → None

Initialize the instance.

Parameters:

• L (NDArrayFloat) – Lower triangle of the precision matrix Cholesky factorization.

• covariance (Optional[NDArrayFloat], optional) – Dense precision matrix, by default None

Raises:

ValueError – _description_

Properties

H	Hermitian adjoint.
L	Lower triangle of the precision matrix Cholesky factorization.
T	Transpose this linear operator.
covariance	Explicit dense representation of the covariance matrix.
log_pdet	Log of the pseudo-determinant of the covariance matrix.
n_pts	Number of points in the domain (n).
ndim
precision	Explicit dense representation of the precision matrix.
rank	Rank of the covariance matrix.
shape	Shape of the covariance matrix (n, n).
subspace_size	Subspace size of the covariance matrix.

Methods

adjoint	Hermitian adjoint.
colorize	Perform a colorizing transformation on data.
dot	Matrix-matrix or matrix-vector multiplication.
from_cholesky	Representation of a covariance provided via choleksy factorization.
from_diagonal	Representation of a covariance provided via diagonal.
from_eigendecomposition	Representation of a covariance provided via eigendecomposition.
from_precision	Return a representation of a covariance from its precision matrix.
get_diagonal	Return the diagonal entries of the matrix (variances).
get_trace	Return the trace of the covariance matrix (sum of diagonal elements).
matmat	Matrix-matrix multiplication.
matvec	Matrix-vector multiplication.
rmatmat	Adjoint matrix-matrix multiplication.
rmatvec	Adjoint matrix-vector multiplication.
sample_mvnormal	Draw samples from the multivariate normal N(0, A).
solve	Solve Ax = b, with A, the current covariance matrix instance.
todense	Explicit dense representation of the covariance matrix with shape (n, n).
transpose	Transpose this linear operator.
whiten	Perform a whitening transformation on data.