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 × Σ × V^T. 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 V^T 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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	SingularValueDecomposition.Solver Specialized solver.

Field Summary

Modifier and Type	Field and Description
private RealMatrix	cachedS Cached value of S (diagonal) matrix.
private final RealMatrix	cachedU Cached value of U matrix.
private RealMatrix	cachedUt Cached value of transposed U matrix.
private final RealMatrix	cachedV Cached value of V matrix.
private RealMatrix	cachedVt Cached value of transposed V matrix.
private static final double	EPS Relative threshold for small singular values.
private final int	m max(row dimension, column dimension).
private final int	n min(row dimension, column dimension).
private final double[]	singularValues Computed singular values.
private static final double	TINY Absolute threshold for small singular values.
private final double	tol Tolerance value for small singular values, calculated once we have populated "singularValues".
private final boolean	transposed Indicator for transposed matrix.

Access	Constructor and Description
public	SingularValueDecomposition(final RealMatrix Matrix to decompose. matrix) Calculates the compact Singular Value Decomposition of the given matrix.

Method Summary

Modifier and Type	Method and Description
public double	Returns: condition number of the matrix getConditionNumber() Return the condition number of the matrix.
public RealMatrix	Returns: covariance matrix getCovariance(final double value below which singular values are ignored (a 0 or negative value implies all singular value will be used) minSingularValue) Returns the n × n covariance matrix.
public double	Returns: the inverse of the condition number. getInverseConditionNumber() Computes the inverse of the condition number.
public double	Returns: norm getNorm() Returns the L₂ norm of the matrix.
public int	Returns: effective numerical matrix rank getRank() Return the effective numerical matrix rank.
public RealMatrix	Returns: the Σ matrix getS() Returns the diagonal matrix Σ of the decomposition.
public double[]	Returns: the diagonal elements of the Σ matrix getSingularValues() Returns the diagonal elements of the matrix Σ of the decomposition.
public DecompositionSolver	Returns: a solver getSolver() Get a solver for finding the A × X = B solution in least square sense.
public RealMatrix	Returns: the U matrix getU() Returns the matrix U of the decomposition.
public RealMatrix	Returns: the U matrix (or null if decomposed matrix is singular) getUT() Returns the transpose of the matrix U of the decomposition.
public RealMatrix	Returns: the V matrix (or null if decomposed matrix is singular) getV() Returns the matrix V of the decomposition.
public RealMatrix	Returns: the V matrix (or null if decomposed matrix is singular) getVT() Returns the transpose of the matrix V of the decomposition.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

cachedS	back to summary
private RealMatrix cachedS Cached value of S (diagonal) matrix.

cachedU	back to summary
private final RealMatrix cachedU Cached value of U matrix.

cachedUt	back to summary
private RealMatrix cachedUt Cached value of transposed U matrix.

cachedV	back to summary
private final RealMatrix cachedV Cached value of V matrix.

cachedVt	back to summary
private RealMatrix cachedVt Cached value of transposed V matrix.

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

m	back to summary
private final int m max(row dimension, column dimension).

n	back to summary
private final int n min(row dimension, column dimension).

singularValues	back to summary
private final double[] singularValues Computed singular values.

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

tol	back to summary
private final double tol Tolerance value for small singular values, calculated once we have populated "singularValues".

transposed	back to summary
private final boolean transposed Indicator for transposed matrix.

SingularValueDecomposition	back to summary
public SingularValueDecomposition(final RealMatrix matrix) Calculates the compact Singular Value Decomposition of the given matrix. Parameters matrix:RealMatrix Matrix to decompose.

Method Detail

getConditionNumber	back to summary
public double getConditionNumber() Return the condition number of the matrix. Returns:double condition number of the matrix

getConditionNumber

back to summary

public double getConditionNumber()

Return the condition number of the matrix.

Returns:double: condition number of the matrix

getCovariance	back to summary
public RealMatrix getCovariance(final double minSingularValue) Returns the n × n covariance matrix. The covariance matrix is V × J × V^T where J is the diagonal matrix of the inverse of the squares of the singular values. Parameters minSingularValue:double value below which singular values are ignored (a 0 or negative value implies all singular value will be used) Returns:RealMatrix covariance matrix Exceptions IllegalArgumentException: if minSingularValue is larger than the largest singular value, meaning all singular values are ignored

getCovariance

back to summary

public RealMatrix getCovariance(final double minSingularValue)

Returns the n × n covariance matrix.

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

Parameters

minSingularValue:double: value below which singular values are ignored (a 0 or negative value implies all singular value will be used)

Returns:RealMatrix

covariance matrix

Exceptions

IllegalArgumentException:: if minSingularValue is larger than the largest singular value, meaning all singular values are ignored

getInverseConditionNumber back to summary

getInverseConditionNumber	back to summary
public double getInverseConditionNumber() Computes the inverse of the condition number. In cases of rank deficiency, the `condition number` will become undefined. Returns:double the inverse of the condition number.

public double getInverseConditionNumber()

Computes the inverse of the condition number. In cases of rank deficiency, the condition number will become undefined.

Returns:double: the inverse of the condition number.

getNorm	back to summary
public double getNorm() Returns the L₂ norm of the matrix. The L₂ norm is max(\|A × u\|₂ / \|u\|₂), where \|.\|₂ denotes the vectorial 2-norm (i.e. the traditional euclidian norm). Returns:double norm

getNorm

back to summary

public double getNorm()

Returns the L₂ norm of the matrix.

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

Returns:double: norm

getRank	back to summary
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(s₁) where ulp(s₁) is the least significant bit of the largest singular value. Returns:int effective numerical matrix rank

getRank

back to summary

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(s₁) where ulp(s₁) is the least significant bit of the largest singular value.

Returns:int: effective numerical matrix rank

getS	back to summary
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:RealMatrix the Σ matrix

getS

back to summary

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:RealMatrix: the Σ matrix

getSingularValues	back to summary
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:double[] the diagonal elements of the Σ matrix

getSingularValues

back to summary

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:double[]: the diagonal elements of the Σ matrix

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

getSolver

back to summary

public DecompositionSolver getSolver()

Get a solver for finding the A × X = B solution in least square sense.

Returns:DecompositionSolver: a solver

getU back to summary

getU	back to summary
public RealMatrix getU() Returns the matrix U of the decomposition. U is an orthogonal matrix, i.e. its transpose is also its inverse. Returns:RealMatrix the U matrix See Also `getUT()`

public RealMatrix getU()

Returns the matrix U of the decomposition.

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

Returns:RealMatrix: the U matrix
See Also: getUT()

getUT back to summary

getUT	back to summary
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:RealMatrix the U matrix (or null if decomposed matrix is singular) See Also `getU()`

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:RealMatrix: the U matrix (or null if decomposed matrix is singular)
See Also: getU()

getV back to summary

getV	back to summary
public RealMatrix getV() Returns the matrix V of the decomposition. V is an orthogonal matrix, i.e. its transpose is also its inverse. Returns:RealMatrix the V matrix (or null if decomposed matrix is singular) See Also `getVT()`

public RealMatrix getV()

Returns the matrix V of the decomposition.

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

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

getVT back to summary

getVT	back to summary
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:RealMatrix the V matrix (or null if decomposed matrix is singular) See Also `getV()`

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

org.apache.commons.math3.linear back to summary

private Class SingularValueDecomposition.Solver

Class Inheritance

extends Object
implements DecompositionSolver

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

All Implemented Interfaces

org.apache.commons.math3.linear.DecompositionSolver

Specialized solver.

Field Summary

Modifier and Type	Field and Description
private boolean	nonSingular Singularity indicator.
private final RealMatrix	pseudoInverse Pseudo-inverse of the initial matrix.

Constructor Summary

Access	Constructor and Description
private	Solver(final double[] Singular values. singularValues, final RealMatrix U^T matrix of the decomposition. uT, final RealMatrix V matrix of the decomposition. v, final boolean Singularity indicator. nonSingular, final double tolerance for singular values tol) Build a solver from decomposed matrix.

Method Summary

Modifier and Type	Method and Description
public RealMatrix	Returns: the inverse matrix. getInverse() Implements org.apache.commons.math3.linear.DecompositionSolver.getInverse. Get the pseudo-inverse of the decomposed matrix.
public boolean	Returns: `true` if the decomposed matrix is non-singular. isNonSingular() Implements org.apache.commons.math3.linear.DecompositionSolver.isNonSingular. Check if the decomposed matrix is non-singular.
public RealVector	Returns: a vector X that minimizes the two norm of A × X - B solve(final RealVector Right-hand side of the equation A × X = B b) Implements org.apache.commons.math3.linear.DecompositionSolver.solve. Solve the linear equation A × X = B in least square sense.
public RealMatrix	Returns: a matrix X that minimizes the two norm of A × X - B solve(final RealMatrix Right-hand side of the equation A × X = B b) Implements org.apache.commons.math3.linear.DecompositionSolver.solve. Solve the linear equation A × X = B in least square sense.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

nonSingular	back to summary
private boolean nonSingular Singularity indicator.

pseudoInverse	back to summary
private final RealMatrix pseudoInverse Pseudo-inverse of the initial matrix.

Constructor Detail

Solver	back to summary
private Solver(final double[] singularValues, final RealMatrix uT, final RealMatrix v, final boolean nonSingular, final double tol) Build a solver from decomposed matrix. Parameters singularValues:double[] Singular values. uT:RealMatrix U^T matrix of the decomposition. v:RealMatrix V matrix of the decomposition. nonSingular:boolean Singularity indicator. tol:double tolerance for singular values

Solver

back to summary

private Solver(final double[] singularValues, final RealMatrix uT, final RealMatrix v, final boolean nonSingular, final double tol)

Build a solver from decomposed matrix.

Parameters

singularValues:double[]: Singular values.
uT:RealMatrix: U^T matrix of the decomposition.
v:RealMatrix: V matrix of the decomposition.
nonSingular:boolean: Singularity indicator.
tol:double: tolerance for singular values

Method Detail

getInverse	back to summary
public RealMatrix getInverse() Implements org.apache.commons.math3.linear.DecompositionSolver.getInverse. Get the pseudo-inverse of the decomposed matrix. Returns:RealMatrix the inverse matrix.

getInverse

back to summary

public RealMatrix getInverse()

Implements org.apache.commons.math3.linear.DecompositionSolver.getInverse.

Get the pseudo-inverse of the decomposed matrix.

Returns:RealMatrix: the inverse matrix.

isNonSingular back to summary

isNonSingular	back to summary
public boolean isNonSingular() Implements org.apache.commons.math3.linear.DecompositionSolver.isNonSingular. Check if the decomposed matrix is non-singular. Returns:boolean `true` if the decomposed matrix is non-singular.

public boolean isNonSingular()

Implements org.apache.commons.math3.linear.DecompositionSolver.isNonSingular.

Check if the decomposed matrix is non-singular.

Returns:boolean: true if the decomposed matrix is non-singular.

solve	back to summary
public RealVector solve(final RealVector b) Implements org.apache.commons.math3.linear.DecompositionSolver.solve. Solve the linear equation A × X = B in least square sense. The m×n matrix A may not be square, the solution X is such that \|\|A × X - B\|\| is minimal. Parameters b:RealVector Right-hand side of the equation A × X = B Returns:RealVector a vector X that minimizes the two norm of A × X - B Exceptions DimensionMismatchException: if the matrices dimensions do not match.

solve

back to summary

public RealVector solve(final RealVector b)

Implements org.apache.commons.math3.linear.DecompositionSolver.solve.

Solve the linear equation A × X = B in least square sense.

The m×n matrix A may not be square, the solution X is such that ||A × X - B|| is minimal.

Parameters

b:RealVector: Right-hand side of the equation A × X = B

Returns:RealVector

a vector X that minimizes the two norm of A × X - B

Exceptions

DimensionMismatchException:: if the matrices dimensions do not match.

solve	back to summary
public RealMatrix solve(final RealMatrix b) Implements org.apache.commons.math3.linear.DecompositionSolver.solve. Solve the linear equation A × X = B in least square sense. The m×n matrix A may not be square, the solution X is such that \|\|A × X - B\|\| is minimal. Parameters b:RealMatrix Right-hand side of the equation A × X = B Returns:RealMatrix a matrix X that minimizes the two norm of A × X - B Exceptions DimensionMismatchException: if the matrices dimensions do not match.

solve

back to summary

public RealMatrix solve(final RealMatrix b)

Implements org.apache.commons.math3.linear.DecompositionSolver.solve.

Solve the linear equation A × X = B in least square sense.

The m×n matrix A may not be square, the solution X is such that ||A × X - B|| is minimal.

Parameters

b:RealMatrix: Right-hand side of the equation A × X = B

Returns:RealMatrix

a matrix X that minimizes the two norm of A × X - B

Exceptions

DimensionMismatchException:: if the matrices dimensions do not match.

public Class SingularValueDecomposition

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class SingularValueDecomposition.Solver

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail