CholeskyFactor

class sksparse.cholmod.CholeskyFactor

The main object used for creating and manipulating a Cholesky factor.

The constructor computes the symbolic analysis of the matrix and determines a fill-reducing ordering (if order is not None or "natural") such that:

\[L L^{\top} = P A P^{\top}.\]

The numeric factorization is not computed until factorize() is called.

Parameters:

• A ((N, N) array_like or sparse array) – An array convertible to a sparse matrix in Compressed Sparse Column (CSC) format.

• sym_kind (str in {“sym”, “row”, “col”}, optional) – The type of factorization for which to analyze the matrix:

  • sym: Symmetric factorization. Only the upper or lower triangular part of the matrix is used (depending on lower), and no check is made for symmetry.

  • row: Unsymmetric factorization of \(A A^{\top}\).

  • col: Unsymmetric factorization of \(A^{\top} A\).

  The resulting matrix must be square and symmetric positive definite.

• supernodal_mode (str in {“auto”, “simplicial”, “supernodal”}, optional) – The type of factorization to use:

  • auto: Automatically select the factorization type.

  • simplicial: Use a simplicial factorization.

  • supernodal: Use a supernodal factorization.

  Default is auto. This mode also applies to any subsequent calls to factorize(). Note that the simplicial mode may be slow for large matrices.

• lower (bool, optional) – If True, use the lower triangular part of A.

• order (str in {“default”, “best”, “natural”, “metis”, “nesdis”, “amd”, “colamd”, “postordered”}, optional) – The permutation algorithm to use for the factorization. Options are:

  • default: Use the default method, which first tries AMD, then METIS.

  • best: Automatically select the best ordering based on the input.

  • metis: Use the METIS library for graph partitioning.

  • nesdis: Use the NESDIS library for nested dissection.

  • amd: Use the Approximate Minimum Degree (AMD) algorithm.

  • colamd: Use the Approximate Minimum Degree (AMD) algorithm for the symmetric case, or the COLAMD algorithm for the unsymmetric case (\(A A^{{\top}}\) or \(A^{{\top}} A\)).

  • postordered: Use natural ordering followed by postordering.

  • natural or None: No permutation is applied (identity permutation).

  By default, methods other than natural will also be postordered.

  Warning

  The ordering method best may be quite slow for large matrices, but if the factorization is reused many times, it can be worth it.

N

The number of rows and columns in the factor.

Type:

int

is_ll

Whether the factor is in LL.T form (True) or LDL.T form (False).

Type:

bool

is_super

Whether the factor is in supernodal (True) or simplicial (False) format.

Type:

bool

itype

The integer type used for indices and indptr in the factor.

Type:

numpy.int32 or numpy.int64

dtype

The data type used for numerical values in the factor.

Type:

numpy.dtype

sym_kind

The symmetry kind used for the factorization.

Type:

str

rcond

A rough estimate of the reciprocal of the condition number of the matrix, defined as (L.diagonal().min() / L.diagonal().max())**2 for an LL.T factorization. Estimated during the numeric factorization. If factorize() has not yet been called, this value is -1.0.

Type:

float

colcount

The number of nonzeros in each column of the factor.

Type:

(N,) numpy.ndarray of int

nnz

The number of nonzeros in the factor.

Type:

int

order

The ordering method used for the factorization. If an unknown ordering was used, returns the integer value.

Type:

str or int

perm

A read-only view of the permutation vector used for the factorization.

Type:

(N,) numpy.ndarray of int

factor

A view of the the Cholesky factor in Compressed Sparse Column (CSC) format. If self.is_ll, the returned matrix is lower triangular. Otherwise, the matrix view contains the lower triangular and the diagonal factors combined.

Note

The view is always in lower triangular form, even if the factor was created using lower=False. To get the upper triangular factor, use get_factor with lower=False. To get the split L and D factors, use get_factor with kind="LDL".

Warning

The returned matrix is a view on the internal data of the CHOLMOD factor. It will be modified if the factor is modified (e.g., by calling factorize()). To get a copy, use get_factor().

Type:

csc_array

L

The lower triangular factor in Compressed Sparse Column (CSC) format.

Type:

csc_array

R

The upper triangular factor in Compressed Sparse Column (CSC) format.

Type:

csc_array

D

A view of the diagonal factor in DIAgonal format. If self.is_ll, this is the identity matrix.

Type:

dia_array

Raises:

CholmodNotPositiveDefiniteError – If the input matrix is structurally singular (e.g., if it is the zero matrix). The input may be numerically indefinite, but this property is not checked until factorize() is called.

See also

cholesky, ldl, cho_factor, ldl_factor

Notes

The symbolic analysis follows that of the SuiteSparse CHOLMOD analyze MATLAB function [1].

Warning

Calling CholeskyFactor.__new__(CholeskyFactor) will leave the object in an “unsafe” state, since the internal CHOLMOD structures will not be initialized. Always use the constructor CholeskyFactor(...) to create a new object.

Added in version 0.1.0.

Changed in version 0.5.0: Refactored to CholeskyFactor from just Factor. Now incorporates Common factor into the object. Major API changes.

References

[1]

analyze.c - CHOLMOD MATLAB analyze function https://github.com/DrTimothyAldenDavis/SuiteSparse/blob/dev/CHOLMOD/MATLAB/analyze.c

Methods

__init__
change_factor	Change the type of factorization used by the object.
copy	Return a copy of the CholeskyFactor object.
det	Compute the determinant of the matrix from its Cholesky factorization.
downdate	Multiple-rank downdate of a sparse LDL factorization.
factorize	Compute the numerical Cholesky factorization of a sparse matrix.
get_factor	Return a copy of the Cholesky factor in the specified format.
get_perm	Return a copy of the permutation vector used in the factorization.
inv	Compute the inverse of the matrix from its Cholesky factorization.
logdet	Compute the (natural) log-determinant of the matrix from its Cholesky factorization.
resymbol	Recompute the symbolic Cholesky factorization of a sparse matrix.
rowadd	Add a row to a sparse LDL factorization.
rowdel	Delete a row from a sparse LDL factorization.
slogdet	Compute the sign and (natural) log-determinant of the matrix from its Cholesky factorization.
solve	Solve the linear system \(A x = b\) for x, using the factorization.
update	Multiple-rank update of a sparse LDL factorization.