HODLRMatrix¶
- class HODLRMatrix(*args)¶
HODLR compressed matrix.
This class provides a compressed representation of dense matrices using Hierarchical Off-Diagonal Low-Rank (HODLR) structure. It is an alternative to
HMatrixthat does not require external dependencies (hmat-oss or STRUMPACK).Methods
addIdentity(alpha)Add a multiple of the identity to the matrix.
applyFactor(y, x)Compute the product with the Cholesky factor.
Add a relative nugget to the diagonal.
assemble(*args)Assemble the matrix from an evaluator.
assembleReal(callable, symmetry)Assemble the matrix from a Python callable.
Return the compression ratio of the matrix.
copy()Copy the matrix.
dump(name)Write a debugging dump of the matrix.
Factorize the matrix using the LLt factorization.
Return the full-rank ratio of the matrix.
gemv(trans, alpha, x, beta, y)Compute a matrix-vector product.
Accessor to the object's name.
Return the diagonal of the matrix.
getId()Accessor to the object's id.
Accessor to the underlying implementation.
getName()Accessor to the object's name.
Return the number of columns.
Return the number of rows.
Return the spatial permutation.
Return the regularization shift used by the last factorization.
Return the log-determinant.
norm()Return the matrix norm.
scale(alpha)Scale the matrix by a scalar.
setName(name)Accessor to the object's name.
setPermutation(permutation)Set the spatial permutation.
solve(*args)Solve a linear system.
solveLower(*args)Solve a linear system with the Cholesky factor.
Notes
This class is experimental.
- __init__(*args)¶
- addIdentity(alpha)¶
Add a multiple of the identity to the matrix. The matrix A is replaced by A + alpha * I. The matrix must be factorized again after this call.
- Parameters:
- alphafloat
Shift to add to the diagonal.
- applyFactor(y, x)¶
Compute the product with the Cholesky factor.
Computes y = L * x, where L is the lower-triangular Cholesky factor of the matrix A, with A = L * L^T. The matrix must have been factorized with the ‘LLt’ or ‘LLT’ method.
The main use is sampling a centered Gaussian random vector of covariance A: if x is a vector of independent standard normal variates, then L * x follows the centered normal distribution of covariance A. Contrary to
gemv(), which computes the full product A * x (and would hence sample a random vector of covariance A^2 from unit noise), this method applies the factor only once.- Parameters:
- ysequence of float
Output vector, updated in place.
- xsequence of float
Input vector.
- applyNugget()¶
Add a relative nugget to the diagonal.
Adds a small multiple of the mean diagonal to the matrix, following the formulation C = sigma^2 I + K used in the HODLR Gaussian-process literature. The relative factor is read from the resource key
HODLRMatrix-Nugget(default0.0); a nonzero value biases every solve by its ratio to the smallest eigenvalue, so keep it at zero unless the leaves need stabilization. The nugget bounds the condition number of ill-conditioned covariance matrices (e.g. long-correlation kernels) and is applied through the same mechanism asaddIdentity().Notes
This method must be called after assembly and before factorization.
- assemble(*args)¶
Assemble the matrix from an evaluator.
- Parameters:
- fcallable
Entry evaluator, such that f(i, j) returns the entry (i, j) of the matrix.
- symmetrystr
Symmetry flag, one of ‘L’ (lower part only, symmetric matrix), ‘U’ (upper part only, symmetric matrix), ‘N’ (no symmetry) or ‘F’ (full matrix).
- assembleReal(callable, symmetry)¶
Assemble the matrix from a Python callable.
- Parameters:
- callablecallable
Python function that takes two integers i and j and returns the entry (i, j) of the matrix.
- symmetrystr
Symmetry flag, one of ‘L’ (lower part only, symmetric matrix), ‘U’ (upper part only, symmetric matrix), ‘N’ (no symmetry) or ‘F’ (full matrix).
- compressionRatio()¶
Return the compression ratio of the matrix.
- Returns:
- ratiosequence of int
Pair (compressedSize, uncompressedSize), where compressedSize is the number of stored coefficients and uncompressedSize is the number of entries of the dense matrix.
- copy()¶
Copy the matrix.
- Returns:
- m
HODLRMatrix A copy of the matrix with its own internal structure.
- m
- dump(name)¶
Write a debugging dump of the matrix.
- Parameters:
- namestr
Name of the dump.
- factorize()¶
Factorize the matrix using the LLt factorization.
- fullrkRatio()¶
Return the full-rank ratio of the matrix.
- Returns:
- ratiosequence of int
Pair (fullRankSize, lowRankSize), where fullRankSize is the number of entries of the dense matrix and lowRankSize is the total storage of the low-rank blocks.
- gemv(trans, alpha, x, beta, y)¶
Compute a matrix-vector product.
Computes y = alpha * A * x + beta * y, where A is the matrix. Only the non-transposed product is supported.
- Parameters:
- transstr
Transpose flag, only ‘N’ is supported.
- alphafloat
Scalar multiplier for A.
- xsequence of float
Input vector.
- betafloat
Scalar multiplier for the output vector.
- ysequence of float
Output vector, updated in place.
- getClassName()¶
Accessor to the object’s name.
- Returns:
- class_namestr
The object class name (object.__class__.__name__).
- getDiagonal()¶
Return the diagonal of the matrix.
- Returns:
- diagonal
Point Diagonal of the matrix, of dimension n.
- diagonal
- getId()¶
Accessor to the object’s id.
- Returns:
- idint
Internal unique identifier.
- getImplementation()¶
Accessor to the underlying implementation.
- Returns:
- implImplementation
A copy of the underlying implementation object.
- getName()¶
Accessor to the object’s name.
- Returns:
- namestr
The name of the object.
- getNbColumns()¶
Return the number of columns.
- Returns:
- nint
Number of columns.
- getNbRows()¶
Return the number of rows.
- Returns:
- nint
Number of rows.
- getPermutation()¶
Return the spatial permutation.
- Returns:
- permutation
Indices The permutation used at assembly time, empty for the identity.
- permutation
- getRegularizationShift()¶
Return the regularization shift used by the last factorization.
When the unregularized Cholesky factorization fails (e.g. on a near-singular covariance matrix), the factorization is retried on A + shift * I with an increasing shift, following the same scheme as
HMatrix. This method returns the shift that was actually applied. A positive value means that the solve() and logDeterminant() results correspond to the regularized matrix rather than to A, and the factorization emits a warning whenever the shift is non-negligible relative to the diagonal (see theHODLRMatrix-RegularizationWarnThresholdresource map key).- Returns:
- shiftfloat
Accumulated regularization shift (0 if the factorization required no regularization).
- logDeterminant()¶
Return the log-determinant.
The matrix must be factorized first.
- Returns:
- logdetfloat
Logarithm of the absolute value of the determinant.
- norm()¶
Return the matrix norm.
This method is not implemented yet.
- scale(alpha)¶
Scale the matrix by a scalar.
The matrix is multiplied by the scalar alpha. The scaling factor is folded into the evaluator and the compressed representation is rebuilt, which invalidates any previous factorization. A call to
factorize()is required before factor-dependent operations such assolve()orlogDeterminant().- Parameters:
- alphafloat
Scaling factor.
- setName(name)¶
Accessor to the object’s name.
- Parameters:
- namestr
The name of the object.
- setPermutation(permutation)¶
Set the spatial permutation.
The matrix is assembled in the permuted order, so this method must be called before
assemble(). The permutation is a bijection of[0, ..., n-1]mapping the permuted index to the original one; an empty permutation restores the original order.- Parameters:
- permutationsequence of int
Permutation of
[0, ..., n-1], or an empty sequence for the identity.
- solve(*args)¶
Solve a linear system.
- Parameters:
- b1-d or 2-d sequence of float
Right-hand side.
- transbool, optional
Whether to solve with the transpose. The transposed solve is not implemented: only False is accepted, and True raises an error. Default is False.
- Returns:
- x1-d or 2-d sequence of float
Solution.
- solveLower(*args)¶
Solve a linear system with the Cholesky factor.
Solves L * x = b (or L^T * x = b if trans is True), where L is the lower Cholesky factor of the matrix. The matrix must have been factorized with the ‘LLt’ or ‘LLT’ method.
- Parameters:
- b1-d or 2-d sequence of float
Right-hand side.
- transbool, optional
Whether to solve with the transpose of the factor. Default is False.
- Returns:
- x1-d or 2-d sequence of float
Solution.
OpenTURNS