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. The matrix must be square and symmetric positive definite. Only the upper or lower triangular part of the matrix is used, and no check is made for symmetry.

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

  • sym: Symmetric factorization. No check is made for symmetry.

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

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

• 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. By default, the natural ordering of the input matrix is used. The other 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.

  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

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

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].

Added in version 0.1.0.

Changed in version 0.5.0: Renamed from Factor. Major API updates to more closely resemble the scipy.linalg.cholesky() dense interface.

References

[1]

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

Methods

__init__
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.