Class SingularValueDecomposition

java.lang.Object
org.apache.commons.math3.linear.SingularValueDecomposition

public class SingularValueDecomposition extends Object
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).

This class is similar to the class with similar name from the JAMA library, with the following changes:

Since:
2.0 (changed to concrete class in 3.0)
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static class 
    Specialized solver.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private RealMatrix
    Cached value of S (diagonal) matrix.
    private final RealMatrix
    Cached value of U matrix.
    private RealMatrix
    Cached value of transposed U matrix.
    private final RealMatrix
    Cached value of V matrix.
    private RealMatrix
    Cached value of transposed V matrix.
    private static final double
    Relative threshold for small singular values.
    private final int
    max(row dimension, column dimension).
    private final int
    min(row dimension, column dimension).
    private final double[]
    Computed singular values.
    private static final double
    Absolute threshold for small singular values.
    private final double
    Tolerance value for small singular values, calculated once we have populated "singularValues".
    private final boolean
    Indicator for transposed matrix.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Calculates the compact Singular Value Decomposition of the given matrix.
  • Method Summary

    Modifier and Type
    Method
    Description
    double
    Return the condition number of the matrix.
    getCovariance(double minSingularValue)
    Returns the n × n covariance matrix.
    double
    Computes the inverse of the condition number.
    double
    Returns the L2 norm of the matrix.
    int
    Return the effective numerical matrix rank.
    Returns the diagonal matrix Σ of the decomposition.
    double[]
    Returns the diagonal elements of the matrix Σ of the decomposition.
    Get a solver for finding the A × X = B solution in least square sense.
    Returns the matrix U of the decomposition.
    Returns the transpose of the matrix U of the decomposition.
    Returns the matrix V of the decomposition.
    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 Details

    • EPS

      private static final double EPS
      Relative threshold for small singular values.
      See Also:
    • TINY

      private static final double TINY
      Absolute threshold for small singular values.
      See Also:
    • singularValues

      private final double[] singularValues
      Computed singular values.
    • m

      private final int m
      max(row dimension, column dimension).
    • n

      private final int n
      min(row dimension, column dimension).
    • transposed

      private final boolean transposed
      Indicator for transposed matrix.
    • cachedU

      private final RealMatrix cachedU
      Cached value of U matrix.
    • cachedUt

      private RealMatrix cachedUt
      Cached value of transposed U matrix.
    • cachedS

      private RealMatrix cachedS
      Cached value of S (diagonal) matrix.
    • cachedV

      private final RealMatrix cachedV
      Cached value of V matrix.
    • cachedVt

      private RealMatrix cachedVt
      Cached value of transposed V matrix.
    • tol

      private final double tol
      Tolerance value for small singular values, calculated once we have populated "singularValues".
  • Constructor Details

    • SingularValueDecomposition

      public SingularValueDecomposition(RealMatrix matrix)
      Calculates the compact Singular Value Decomposition of the given matrix.
      Parameters:
      matrix - Matrix to decompose.
  • Method Details

    • getU

      public RealMatrix getU()
      Returns the matrix U of the decomposition.

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

      Returns:
      the U matrix
      See Also:
    • getUT

      public RealMatrix getUT()
      Returns the transpose of the matrix U of the decomposition.

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

      Returns:
      the U matrix (or null if decomposed matrix is singular)
      See Also:
    • getS

      public RealMatrix getS()
      Returns the diagonal matrix Σ of the decomposition.

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

      Returns:
      the Σ matrix
    • getSingularValues

      public double[] getSingularValues()
      Returns the diagonal elements of the matrix Σ of the decomposition.

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

      Returns:
      the diagonal elements of the Σ matrix
    • getV

      public RealMatrix getV()
      Returns the matrix V of the decomposition.

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

      Returns:
      the V matrix (or null if decomposed matrix is singular)
      See Also:
    • getVT

      public RealMatrix getVT()
      Returns the transpose of the matrix V of the decomposition.

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

      Returns:
      the V matrix (or null if decomposed matrix is singular)
      See Also:
    • 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.

      Parameters:
      minSingularValue - value below which singular values are ignored (a 0 or negative value implies all singular value will be used)
      Returns:
      covariance matrix
      Throws:
      IllegalArgumentException - if minSingularValue is larger than the largest singular value, meaning all singular values are ignored
    • getNorm

      public double getNorm()
      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).

      Returns:
      norm
    • getConditionNumber

      public double getConditionNumber()
      Return the condition number of the matrix.
      Returns:
      condition number of the matrix
    • getInverseConditionNumber

      public double getInverseConditionNumber()
      Computes the inverse of the condition number. In cases of rank deficiency, the condition number will become undefined.
      Returns:
      the inverse of the condition number.
    • getRank

      public int getRank()
      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.

      Returns:
      effective numerical matrix rank
    • getSolver

      public DecompositionSolver getSolver()
      Get a solver for finding the A × X = B solution in least square sense.
      Returns:
      a solver