covmats.CovViaSparsePrecisionCholesky#

class covmats.CovViaSparsePrecisionCholesky(*args, **kwargs)[source]#

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

Notes

Let the covariance matrix be \(\mathbf{A}\), its precision matrix be \(\mathbf{Q} = \mathbf{A}^{-1}\), and let \(\mathbf{L}\mathbf{D}\mathbf{L}^{T} = \mathbf{P}\mathbf{Q}\mathbf{P}^{T}\) be the sparse \(\mathbf{L}\mathbf{D}\mathbf{L}^{T}\) factorization of \(\mathbf{Q}\) (see SparseCholeskyFactor).

Products with the covariance matrix and whitening/colorizing operations are obtained by solving sparse triangular systems involving L and D, so that the dense covariance matrix \(\mathbf{A}\) is never built explicitly. This makes this representation well suited to large-scale, sparse precision matrices such as those arising from Markov random fields or SPDE-based Gaussian random fields.

This Covariance class does not support singular covariance/precision matrices because the Cholesky-like factorization does not exist for a singular matrix.

Examples

>>> import numpy as np
>>> import scipy as sp
>>> import covmats
>>> Q = covmats.get_SPD_sparse_n11_example(seed=42)  # sparse precision
>>> L, D, P = sp.linalg.ldl(Q.toarray())  # dense LDL' for the example
>>> scf = covmats.SparseCholeskyFactor(
...     sp.sparse.csc_array(L), sp.sparse.csc_array(D), P
... )
>>> cov = covmats.CovViaSparsePrecisionCholesky(scf)
>>> x = np.random.default_rng(0).random(Q.shape[0])
>>> np.allclose(cov.solve(cov @ x), x)
True

__init__(scf: SparseCholeskyFactor, sparse_precision: sparray | None = None) → None[source]#

Initialize the instance.

Parameters:

scf (SparseCholeskyFactor) – Lower triangle of the sparse precision matrix Cholesky factorization.
sparse_precision (Optional[sp.sparse.sparray], optional) – Sparse precision matrix (inverse of the covariance matrix), by default None

Properties

`H`	Hermitian adjoint.
`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 with shape (n, n).
`rank`	Rank of the covariance matrix.
`scf`
`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.
`colorize_adjoint`	Perform the adjoint (transpose) of the colorizing transformation.
`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`	Return x = A^{-1} b.
`todense`	Explicit dense representation of the covariance matrix with shape (n, n).
`transpose`	Transpose this linear operator.
`whiten`	Perform a whitening transformation on data.