Interface TriangularDecomp

All Known Implementing Classes:
CholeskyDecomp, LUDecomp

public interface TriangularDecomp
Interface representing common operations for triangular decompositions of matrices. The BZDev class library contains implementations of two decompositions: LU decomposition and Cholesky decomposition. If a matrix has a Cholesky decomposition, the matrix must be a Hermetian positive semi-definite matrix. Java does not have built-in operations for complex numbers, however, so for this class library, Hermetian matrices must be symmetric matrices. An LU decomposition does not have this constraint, but is slower to compute.

We assume that the decomposition of a matrix A determines matrices L, U, and P where L is a lower triangular matrix, U is an upper triangular matrix, P is a permutation matrix, and LU = PA. For the case of Cholesky decomposition, P will be the identity matrix and U will be the transpose of L.

LU and Cholesky decompositions are used for a number of purposes, including solving linear equations, and computing the inverses of matrices. An interface for common operations is useful for cases where the type of decomposition to use can only be determined at run time. For example, in cases where Cholesky decomposition will work in the vast majority of cases, one could use the following code:

      public TriangularDecomp decompose(double[][] matrix) {
         try {
           return CholeskyDecomp(matrix);
         } catch (Exception e) {
           return LUDecomp(matrix);
         }
      }
 
This method tries Cholesky decomposition, and if that fails, it falls back on LU decomposition. One can then use the TriangularDecomp object returned to solve a set of linear equations or to compute the inverse of the original matrix.
  • Method Summary

    Modifier and Type
    Method
    Description
    double
    det()
    Get the determinate of the matrix to which this decomposition applies.
    double[][]
    Get the inverse of a matrix.
    void
    getInverse(double[][] result)
    Get the inverse of a matrix and store the inverse.
    void
    getInverse(double[] result, boolean columnMajorOrder)
    Get the inverse of a matrix and store the inverse in a flat matrix.
    double[][]
    Get the lower triangular matrix associated with the decomposition.
    int
    Get the number of columns in the triangular matrices associated with an instance of this class.
    int
    Get the number of rows in the triangular matrices associated with an instance of this class.
    Get the permutation to which this decomposition applies.
    double[][]
    Get the upper triangular matrix associated with the decomposition.
    boolean
    Determine if the matrix to which this decomposition applies is nonsingular.
    double[]
    solve(double[] b)
    Solve the system of linear equations Ax = b where x and b are vectors and A is the matrix to which this decomposition applies.
    void
    solve(double[][] x, double[][] b)
    Solve the system of linear equations AX = B where X and B are matrices and A is the matrix to which this decomposition applies.
    void
    solve(double[] x, double[] b)
    Solve the system of linear equations Ax = b where x and b are vectors and A is the matrix to which this decomposition applies.
  • Method Details

    • getNumberOfRows

      int getNumberOfRows()
      Get the number of rows in the triangular matrices associated with an instance of this class.
      Returns:
      the number of rows.
    • getNumberOfColumns

      int getNumberOfColumns()
      Get the number of columns in the triangular matrices associated with an instance of this class.
      Returns:
      the number of columns.
    • det

      double det() throws IllegalStateException
      Get the determinate of the matrix to which this decomposition applies.
      Returns:
      the determinate
      Throws:
      IllegalStateException - - if the matrix to which this decomposition applies is not a square matrix
    • getP

      Permutation getP()
      Get the permutation to which this decomposition applies. The permutation returned has the property that its getMatrix() method returns the permutation matrix.
      Returns:
      the permutation
    • getL

      double[][] getL()
      Get the lower triangular matrix associated with the decomposition.
      Returns:
      the lower triangular matrix
    • getU

      double[][] getU()
      Get the upper triangular matrix associated with the decomposition. For Cholesky decomposition, U is the transpose of the lower triangular matrix returned by getL().
      Returns:
      the upper triangular matrix
    • isNonsingular

      boolean isNonsingular()
      Determine if the matrix to which this decomposition applies is nonsingular.
      Returns:
      true if the matrix is nonsingular; false otherwise
    • solve

      double[] solve(double[] b) throws IllegalArgumentException, IllegalStateException
      Solve the system of linear equations Ax = b where x and b are vectors and A is the matrix to which this decomposition applies.
      Parameters:
      b - the vector b in the equation Ax = b
      Returns:
      the vector x that satisfies the equation Ax = b
      Throws:
      IllegalArgumentException - the argument has the wrong size
      IllegalStateException - the matrix this object decomposed is a singular matrix
    • solve

      void solve(double[] x, double[] b) throws IllegalArgumentException, IllegalStateException
      Solve the system of linear equations Ax = b where x and b are vectors and A is the matrix to which this decomposition applies. The vector x will be modified.
      Parameters:
      b - the vector b in the equation Ax = b
      x - the vector x that satisfies the equation Ax = b
      Throws:
      IllegalArgumentException - the argument has the wrong size
      IllegalStateException - the matrix this object decomposed is a singular matrix
    • solve

      void solve(double[][] x, double[][] b) throws IllegalArgumentException, IllegalStateException
      Solve the system of linear equations AX = B where X and B are matrices and A is the matrix to which this decomposition applies. The matrix X will be modified.
      Parameters:
      b - the matrix B in the equation AX = B
      x - the matrix X that satisfies the equation AX = B
      Throws:
      IllegalArgumentException - the arguments have the wrong size
      IllegalStateException - the matrix this object decomposed is a singular matrix
    • getInverse

      double[][] getInverse()
      Get the inverse of a matrix. The matrix A whose inverse is computed satisfies PA = LU, where P is the permutation matrix associated with this instance, L is the lower triangular matrix associated with this instance, and U is the upper triangular matrix associated with this instance.

      For some cases (e.g., Cholesky decomposition), the permutation matrix is the identity matrix.

      Returns:
      the inverse of the matrix that this instance decomposed
      Throws:
      IllegalStateException - the matrix is singular
    • getInverse

      void getInverse(double[][] result) throws IllegalStateException, IllegalArgumentException
      Get the inverse of a matrix and store the inverse. The matrix A whose inverse is computed satisfies PA = LU, where P is the permutation matrix associated with this instance, L is the lower triangular matrix associated with this instance, and U is the upper triangular matrix associated with this instance.
      Parameters:
      result - the matrix holding the inverse
      Throws:
      IllegalStateException - the matrix is singular
      IllegalArgumentException - - if result has the wrong dimensions
    • getInverse

      void getInverse(double[] result, boolean columnMajorOrder) throws IllegalStateException, IllegalArgumentException
      Get the inverse of a matrix and store the inverse in a flat matrix. The matrix A whose inverse is computed satisfies A = LLT, where L is the lower triangular matrix associated with this instance.
      Parameters:
      result - the matrix holding the inverse
      columnMajorOrder - true if the inverse is stored in column major order (e.g., the order used by Fortran); false if the inverse is stored in row-major-order (e.g., the order used by C)
      Throws:
      IllegalStateException - the matrix is singular
      IllegalArgumentException - - if result has the wrong dimensions