org.apache.commons.math3.linear
Class SingularValueDecomposition

java.lang.Object
  extended by 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)
Version:
$Id: SingularValueDecomposition.java 1416643 2012-12-03 19:37:14Z tn $
See Also:
MathWorld, Wikipedia

Nested Class Summary
private static class SingularValueDecomposition.Solver
          Specialized solver.
 
Field Summary
private  RealMatrix cachedS
          Cached value of S (diagonal) matrix.
private  RealMatrix cachedU
          Cached value of U matrix.
private  RealMatrix cachedUt
          Cached value of transposed U matrix.
private  RealMatrix cachedV
          Cached value of V matrix.
private  RealMatrix cachedVt
          Cached value of transposed V matrix.
private static double EPS
          Relative threshold for small singular values.
private  int m
          max(row dimension, column dimension).
private  int n
          min(row dimension, column dimension).
private  double[] singularValues
          Computed singular values.
private static double TINY
          Absolute threshold for small singular values.
private  double tol
          Tolerance value for small singular values, calculated once we have populated "singularValues".
private  boolean transposed
          Indicator for transposed matrix.
 
Constructor Summary
SingularValueDecomposition(RealMatrix matrix)
          Calculates the compact Singular Value Decomposition of the given matrix.
 
Method Summary
 double getConditionNumber()
          Return the condition number of the matrix.
 RealMatrix getCovariance(double minSingularValue)
          Returns the n × n covariance matrix.
 double getInverseConditionNumber()
          Computes the inverse of the condition number.
 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

EPS

private static final double EPS
Relative threshold for small singular values.

See Also:
Constant Field Values

TINY

private static final double TINY
Absolute threshold for small singular values.

See Also:
Constant Field Values

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 Detail

SingularValueDecomposition

public SingularValueDecomposition(RealMatrix matrix)
Calculates the compact Singular Value Decomposition of the given matrix.

Parameters:
matrix - Matrix to decompose.
Method Detail

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()

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:
getU()

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()

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:
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.

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


Copyright (c) 2003-2013 Apache Software Foundation