org.apache.commons.math.linear

## Class SingularValueDecompositionImpl

- java.lang.Object
- - org.apache.commons.math.linear.SingularValueDecompositionImpl

- All Implemented Interfaces:
    SingularValueDecomposition

      public class SingularValueDecompositionImpl
      extends Object
      implements SingularValueDecomposition

  Calculates the compact Singular Value Decomposition of a matrix.

  The Singular Value Decomposition of matrix A is a set of three matrices: U, Σ and V such that A = U × Σ × VT. Let A be a m × n matrix, then U is a m × p orthogonal matrix, Σ is a p × p diagonal matrix with positive or null elements, V is a p × n orthogonal matrix (hence VT is also orthogonal) where p=min(m,n).

  Since:
    2.0
  Version:
    $Revision: 990655 $ $Date: 2010-08-29 23:49:40 +0200 (dim. 29 août 2010) $

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `private static class` | `SingularValueDecompositionImpl.Solver` Specialized solver.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private RealMatrix` | `cachedS` Cached value of S.
    `private RealMatrix` | `cachedU` Cached value of U.
    `private RealMatrix` | `cachedUt` Cached value of UT.
    `private RealMatrix` | `cachedV` Cached value of V.
    `private RealMatrix` | `cachedVt` Cached value of VT.
    `private EigenDecomposition` | `eigenDecomposition` Eigen decomposition of the tridiagonal matrix.
    `private int` | `m` Number of rows of the initial matrix.
    `private int` | `n` Number of columns of the initial matrix.
    `private double[]` | `singularValues` Singular values.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SingularValueDecompositionImpl(RealMatrix matrix)` Calculates the compact Singular Value Decomposition of the given matrix.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `double` | `getConditionNumber()` Return the condition number of the matrix.
    `RealMatrix` | `getCovariance(double minSingularValue)` Returns the n × n covariance matrix.
    `double` | `getNorm()` Returns the L2 norm of the matrix.
    `int` | `getRank()` Return the effective numerical matrix rank.
    `RealMatrix` | `getS()` Returns the diagonal matrix Σ of the decomposition.
    `double[]` | `getSingularValues()` Returns the diagonal elements of the matrix Σ of the decomposition.
    `DecompositionSolver` | `getSolver()` Get a solver for finding the A × X = B solution in least square sense.
    `RealMatrix` | `getU()` Returns the matrix U of the decomposition.
    `RealMatrix` | `getUT()` Returns the transpose of the matrix U of the decomposition.
    `RealMatrix` | `getV()` Returns the matrix V of the decomposition.
    `RealMatrix` | `getVT()` Returns the transpose of the matrix V of the decomposition.

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

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

- - ### Field Detail

    - #### m

          private int m

      Number of rows of the initial matrix.

    - #### n

          private int n

      Number of columns of the initial matrix.

    - #### eigenDecomposition

          private EigenDecomposition eigenDecomposition

      Eigen decomposition of the tridiagonal matrix.

    - #### singularValues

          private double[] singularValues

      Singular values.

    - #### cachedU

          private RealMatrix cachedU

      Cached value of U.

    - #### cachedUt

          private RealMatrix cachedUt

      Cached value of UT.

    - #### cachedS

          private RealMatrix cachedS

      Cached value of S.

    - #### cachedV

          private RealMatrix cachedV

      Cached value of V.

    - #### cachedVt

          private RealMatrix cachedVt

      Cached value of VT.

  - ### Constructor Detail

    - #### SingularValueDecompositionImpl

          public SingularValueDecompositionImpl(RealMatrix matrix)
                                         throws InvalidMatrixException

      Calculates the compact Singular Value Decomposition of the given matrix.
      Parameters:
        `matrix` - The matrix to decompose.
      Throws:
        `InvalidMatrixException` - (wrapping a `ConvergenceException` if algorithm fails to converge

  - ### Method Detail

    - #### getU

          public RealMatrix getU()
                          throws InvalidMatrixException

      Returns the matrix U of the decomposition.

      U is an orthogonal matrix, i.e. its transpose is also its inverse.

      Specified by:
        `getU` in interface `SingularValueDecomposition`
      Returns:
        the U matrix
      Throws:
        `InvalidMatrixException`
      See Also:
        `SingularValueDecomposition.getUT()`

    - #### getUT

          public RealMatrix getUT()
                           throws InvalidMatrixException

      Returns the transpose of the matrix U of the decomposition.

      U is an orthogonal matrix, i.e. its transpose is also its inverse.

      Specified by:
        `getUT` in interface `SingularValueDecomposition`
      Returns:
        the U matrix (or null if decomposed matrix is singular)
      Throws:
        `InvalidMatrixException`
      See Also:
        `SingularValueDecomposition.getU()`

    - #### getS

          public RealMatrix getS()
                          throws InvalidMatrixException

      Returns the diagonal matrix Σ of the decomposition.

      Σ is a diagonal matrix. The singular values are provided in non-increasing order, for compatibility with Jama.

      Specified by:
        `getS` in interface `SingularValueDecomposition`
      Returns:
        the Σ matrix
      Throws:
        `InvalidMatrixException`

    - #### getSingularValues

          public double[] getSingularValues()
                                     throws InvalidMatrixException

      Returns the diagonal elements of the matrix Σ of the decomposition.

      The singular values are provided in non-increasing order, for compatibility with Jama.

      Specified by:
        `getSingularValues` in interface `SingularValueDecomposition`
      Returns:
        the diagonal elements of the Σ matrix
      Throws:
        `InvalidMatrixException`

    - #### getV

          public RealMatrix getV()
                          throws InvalidMatrixException

      Returns the matrix V of the decomposition.

      V is an orthogonal matrix, i.e. its transpose is also its inverse.

      Specified by:
        `getV` in interface `SingularValueDecomposition`
      Returns:
        the V matrix (or null if decomposed matrix is singular)
      Throws:
        `InvalidMatrixException`
      See Also:
        `SingularValueDecomposition.getVT()`

    - #### getVT

          public RealMatrix getVT()
                           throws InvalidMatrixException

      Returns the transpose of the matrix V of the decomposition.

      V is an orthogonal matrix, i.e. its transpose is also its inverse.

      Specified by:
        `getVT` in interface `SingularValueDecomposition`
      Returns:
        the V matrix (or null if decomposed matrix is singular)
      Throws:
        `InvalidMatrixException`
      See Also:
        `SingularValueDecomposition.getV()`

    - #### getCovariance

          public RealMatrix getCovariance(double minSingularValue)

      Returns the n × n covariance matrix.

      The covariance matrix is V × J × VT where J is the diagonal matrix of the inverse of the squares of the singular values.

      Specified by:
        `getCovariance` in interface `SingularValueDecomposition`
      Parameters:
        `minSingularValue` - value below which singular values are ignored (a 0 or negative value implies all singular value will be used)
      Returns:
        covariance matrix

    - #### getNorm

          public double getNorm()
                         throws InvalidMatrixException

      Returns the L2 norm of the matrix.

      The L2 norm is max(|A × u|2 / |u|2), where |.|2 denotes the vectorial 2-norm (i.e. the traditional euclidian norm).

      Specified by:
        `getNorm` in interface `SingularValueDecomposition`
      Returns:
        norm
      Throws:
        `InvalidMatrixException`

    - #### getConditionNumber

          public double getConditionNumber()
                                    throws InvalidMatrixException

      Return the condition number of the matrix.
      Specified by:
        `getConditionNumber` in interface `SingularValueDecomposition`
      Returns:
        condition number of the matrix
      Throws:
        `InvalidMatrixException`

    - #### getRank

          public int getRank()
                      throws IllegalStateException

      Return the effective numerical matrix rank.

      The effective numerical rank is the number of non-negligible singular values. The threshold used to identify non-negligible terms is max(m,n) × ulp(s1) where ulp(s1) is the least significant bit of the largest singular value.

      Specified by:
        `getRank` in interface `SingularValueDecomposition`
      Returns:
        effective numerical matrix rank
      Throws:
        `IllegalStateException`

    - #### getSolver

          public DecompositionSolver getSolver()

      Get a solver for finding the A × X = B solution in least square sense.
      Specified by:
        `getSolver` in interface `SingularValueDecomposition`
      Returns:
        a solver

Copyright (c) 2003-2013 Apache Software Foundation