org.apache.commons.math3.linear

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

- the `norm2` method which has been renamed as `getNorm`,
- the `cond` method which has been renamed as `getConditionNumber`,
- the `rank` method which has been renamed as `getRank`,
- a `getUT` method has been added,
- a `getVT` method has been added,
- a `getSolver` method has been added,
- a `getCovariance` method has been added.

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

Nested Classes
`private static class` `SingularValueDecomposition.Solver` Specialized solver.

### Field Summary

Fields
`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

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

### Method Summary

Methods
`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