org.apache.commons.math3.linear

## Class RectangularCholeskyDecomposition

- java.lang.Object
- - org.apache.commons.math3.linear.RectangularCholeskyDecomposition

-     public class RectangularCholeskyDecomposition
      extends Object

  Calculates the rectangular Cholesky decomposition of a matrix.

  The rectangular Cholesky decomposition of a real symmetric positive semidefinite matrix A consists of a rectangular matrix B with the same number of rows such that: A is almost equal to BBT, depending on a user-defined tolerance. In a sense, this is the square root of A.

  The difference with respect to the regular `CholeskyDecomposition` is that rows/columns may be permuted (hence the rectangular shape instead of the traditional triangular shape) and there is a threshold to ignore small diagonal elements. This is used for example to generate `correlated random n-dimensions vectors` in a p-dimension subspace (p < n). In other words, it allows generating random vectors from a covariance matrix that is only positive semidefinite, and not positive definite.

  Rectangular Cholesky decomposition is not suited for solving linear systems, so it does not provide any `decomposition solver`.

  Since:
    2.0 (changed to concrete class in 3.0)
  Version:
    $Id: RectangularCholeskyDecomposition.java 1422313 2012-12-15 18:53:41Z psteitz $
  See Also:
    MathWorld, Wikipedia

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private int` | `rank` Rank of the symmetric positive semidefinite matrix.
    `private RealMatrix` | `root` Permutated Cholesky root of the symmetric positive semidefinite matrix.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RectangularCholeskyDecomposition(RealMatrix matrix)` Decompose a symmetric positive semidefinite matrix.
    `RectangularCholeskyDecomposition(RealMatrix matrix, double small)` Decompose a symmetric positive semidefinite matrix.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getRank()` Get the rank of the symmetric positive semidefinite matrix.
    `RealMatrix` | `getRootMatrix()` Get the root of the covariance matrix.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### root

          private final RealMatrix root

      Permutated Cholesky root of the symmetric positive semidefinite matrix.

    - #### rank

          private int rank

      Rank of the symmetric positive semidefinite matrix.

  - ### Constructor Detail

    - #### RectangularCholeskyDecomposition

          public RectangularCholeskyDecomposition(RealMatrix matrix)
                                           throws NonPositiveDefiniteMatrixException

      Decompose a symmetric positive semidefinite matrix.

      Note: this constructor follows the linpack method to detect dependent columns by proceeding with the Cholesky algorithm until a nonpositive diagonal element is encountered.

      Parameters:
        `matrix` - Symmetric positive semidefinite matrix.
      Throws:
        `NonPositiveDefiniteMatrixException` - if the matrix is not positive semidefinite.
      Since:
        3.1
      See Also:
        Analysis of the Cholesky Decomposition of a Semi-definite Matrix

    - #### RectangularCholeskyDecomposition

          public RectangularCholeskyDecomposition(RealMatrix matrix,
                                          double small)
                                           throws NonPositiveDefiniteMatrixException

      Decompose a symmetric positive semidefinite matrix.
      Parameters:
        `matrix` - Symmetric positive semidefinite matrix.
        `small` - Diagonal elements threshold under which columns are considered to be dependent on previous ones and are discarded.
      Throws:
        `NonPositiveDefiniteMatrixException` - if the matrix is not positive semidefinite.

  - ### Method Detail

    - #### getRootMatrix

          public RealMatrix getRootMatrix()

      Get the root of the covariance matrix. The root is the rectangular matrix `B` such that the covariance matrix is equal to `B.BT`
      Returns:
        root of the square matrix
      See Also:
        `getRank()`

    - #### getRank

          public int getRank()

      Get the rank of the symmetric positive semidefinite matrix. The r is the number of independent rows in the symmetric positive semidefinite matrix, it is also the number of columns of the rectangular matrix of the decomposition.
      Returns:
        r of the square matrix.
      See Also:
        `getRootMatrix()`

Copyright (c) 2003-2013 Apache Software Foundation