Class Cholesky<T extends MatrixMixin<T,?,?,?>>

java.lang.Object
org.flag4j.linalg.decompositions.Decomposition<T>
org.flag4j.linalg.decompositions.chol.Cholesky<T>
Type Parameters:
T - The type of matrix on which the Cholesky decomposition is performed, extending MatrixMixin.
Direct Known Subclasses:
ComplexCholesky, RealCholesky
public abstract class Cholesky<T extends MatrixMixin<T,?,?,?>> extends Decomposition<T>

An abstract base class for Cholesky decomposition of symmetric (or Hermitian) positive-definite matrices.

The Cholesky decomposition factorizes a symmetric/Hermitian, positive-definite matrix \( A \) as: \[ A = LL^{H} \] where \( L \) is a lower triangular matrix. The decomposition is primarily used for efficient numerical solutions to linear systems, computing matrix inverses, and generating samples from multivariate normal distributions.

Hermitian Verification:

This class provides an option to explicitly check whether the input matrix is Hermitian. If enforceHermitian is set to true, the implementation will verify that \( A \) satisfies \( A = A^{H} \) before performing decomposition. If set to false, the matrix is assumed to be Hermitian, no explicit check will be performed, and only the lower-diagonal entries of \( A \) are accessed.

positive-definiteness Check:

To ensure numerical stability, the algorithm verifies that all diagonal entries of \( L \) are positive. A tolerance threshold, posDefTolerance, is used to determine whether a diagonal entry is considered non-positive, indicating that the matrix is not positive-definite. This threshold can be adjusted using setPosDefTolerance(double).

Usage:

A typical workflow using a concrete implementation of Cholesky decomposition follows these steps:

  1. Instantiate a subclass of Cholesky.
  2. Call Decomposition.decompose(MatrixMixin) to compute the decomposition.
  3. Retrieve the factorized matrices using getL() or getLH().
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected boolean
    enforceHermitian
    Flag indicating if an explicit check should be made that the matrix to be decomposed is Hermitian.
    protected T
    L
    The lower triangular matrix, \( L \), resulting from the Cholesky decomposition \( A = LL^{H} \).
    protected double
    posDefTolerance
    Tolerance for determining if an entry along the diagonal of \( L \) is not positive-definite.
    protected static final String
    SYM_POS_DEF_ERR
    Error message to display when the matrix to be decomposed is not symmetric positive-definite.

    Fields inherited from class org.flag4j.linalg.decompositions.Decomposition

    hasDecomposed

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Cholesky(boolean enforceHermitian)
    Constructs a Cholesky decomposer.

  • Method Summary

    Modifier and Type
    Method
    Description
    T
    getL()
    Gets the L matrix computed by the Cholesky decomposition \( A = LL^{H} \).
    T
    getLH()
    Gets the \( L^{H} \) matrix computed by the Cholesky decomposition \( A = LL^{H} \).
    void
    setPosDefTolerance(double tol)
    Sets the tolerance for determining if the matrix being decomposed is positive-definite.

    Methods inherited from class org.flag4j.linalg.decompositions.Decomposition

    decompose, ensureHasDecomposed

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • SYM_POS_DEF_ERR

      protected static final String SYM_POS_DEF_ERR
      Error message to display when the matrix to be decomposed is not symmetric positive-definite.
      See Also:

    • enforceHermitian

      protected boolean enforceHermitian
      Flag indicating if an explicit check should be made that the matrix to be decomposed is Hermitian.
      • If true, the matrix will be explicitly verified to be Hermitian.
      • If false, no check will be made to verify the matrix is Hermitian, and it will be assumed to be.

    • posDefTolerance

      protected double posDefTolerance
      Tolerance for determining if an entry along the diagonal of \( L \) is not positive-definite.

    • L

      protected T extends MatrixMixin<T,?,?,?> L
      The lower triangular matrix, \( L \), resulting from the Cholesky decomposition \( A = LL^{H} \).

  • Constructor Details

    • Cholesky

      protected Cholesky(boolean enforceHermitian)
      Constructs a Cholesky decomposer.
      Parameters:
      enforceHermitian - Flat indicating if an explicit check should be made that the matrix to be decomposed is Hermitian.
      • If true, the matrix will be explicitly verified to be Hermitian.
      • If false, no check will be made to verify the matrix is Hermitian, and it will be assumed to be.
      inPlace - Flag indicating if the decomposition should be done in-place.
      • If true, the decomposition will be done in-place overwriting the original matrix.
      • If false, the decomposition will be done out-of-place leaving the original matrix unmodified.

  • Method Details

    • setPosDefTolerance

      public void setPosDefTolerance(double tol)

      Sets the tolerance for determining if the matrix being decomposed is positive-definite.

      The matrix being decomposed will be considered to not be positive-definite if any diagonal entry of \( L \) is <= tol. By default, this value is 1.0e-14.

      Parameters:
      tol - Tolerance to use. Must be non-negative.
      Throws:
      IllegalArgumentException - If tol < 0.

    • getL

      public T getL()
      Gets the L matrix computed by the Cholesky decomposition \( A = LL^{H} \).
      Returns:
      The \( L \) matrix from the Cholesky decomposition \( A = LL^{H} \).
      Throws:
      IllegalStateException - If Decomposition.decompose(MatrixMixin) has not been called on this instance.

    • getLH

      public T getLH()
      Gets the \( L^{H} \) matrix computed by the Cholesky decomposition \( A = LL^{H} \).
      Returns:
      The \( L^{H} \) matrix from the Cholesky decomposition \( A = LL^{H} \).
      Throws:
      IllegalStateException - If Decomposition.decompose(MatrixMixin) has not been called on this instance.