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 HMatrix that 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.

applyNugget()

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.

compressionRatio()

Return the compression ratio of the matrix.

copy()

Copy the matrix.

dump(name)

Write a debugging dump of the matrix.

factorize()

Factorize the matrix using the LLt factorization.

fullrkRatio()

Return the full-rank ratio of the matrix.

gemv(trans, alpha, x, beta, y)

Compute a matrix-vector product.

getClassName()

Accessor to the object's name.

getDiagonal()

Return the diagonal of the matrix.

getId()

Accessor to the object's id.

getImplementation()

Accessor to the underlying implementation.

getName()

Accessor to the object's name.

getNbColumns()

Return the number of columns.

getNbRows()

Return the number of rows.

getPermutation()

Return the spatial permutation.

getRegularizationShift()

Return the regularization shift used by the last factorization.

logDeterminant()

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 (default 0.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 as addIdentity().

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:
mHODLRMatrix

A copy of the matrix with its own internal structure.

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:
diagonalPoint

Diagonal of the matrix, of dimension n.

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:
permutationIndices

The permutation used at assembly time, empty for the identity.

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 the HODLRMatrix-RegularizationWarnThreshold resource 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 as solve() or logDeterminant().

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.