Module ojalgo

Package org.ojalgo.matrix.decomposition

Class RawSingularValue

java.lang.Object

org.ojalgo.matrix.decomposition.AbstractDecomposition<java.lang.Double,R064Store>

org.ojalgo.matrix.decomposition.RawDecomposition

org.ojalgo.matrix.decomposition.RawSingularValue

All Implemented Interfaces:

MatrixDecomposition<java.lang.Double>, MatrixDecomposition.EconomySize<java.lang.Double>, MatrixDecomposition.Ordered<java.lang.Double>, MatrixDecomposition.RankRevealing<java.lang.Double>, MatrixDecomposition.Solver<java.lang.Double>, MatrixDecomposition.Values<java.lang.Double>, SingularValue<java.lang.Double>, Provider2D, Provider2D.Condition, Provider2D.Inverse<java.util.Optional<MatrixStore<java.lang.Double>>>, Provider2D.Rank, Provider2D.Solution<java.util.Optional<MatrixStore<java.lang.Double>>>, InverterTask<java.lang.Double>, MatrixTask<java.lang.Double>, SolverTask<java.lang.Double>, InvertibleFactor<java.lang.Double>, Structure1D, Structure2D

final class RawSingularValue
extends RawDecomposition
implements SingularValue<java.lang.Double>

Singular Value Decomposition.

For an m-by-n matrix A with m >= n, the singular value decomposition is an m-by-n orthogonal matrix U, an n-by-n diagonal matrix S, and an n-by-n orthogonal matrix V so that A = U*S*V'.

The singular values, sigma[k] = S[k][k], are ordered so that sigma[0] >= sigma[1] >= ... >= sigma[n-1].

The singular value decompostion always exists, so the constructor will never fail. The matrix condition number and the effective numerical rank can be computed from this decomposition.

Nested Class Summary

Nested classes/interfaces inherited from interface org.ojalgo.matrix.transformation.InvertibleFactor

InvertibleFactor.IdentityFactor<N extends java.lang.Comparable<N>>

Nested classes/interfaces inherited from interface org.ojalgo.matrix.decomposition.MatrixDecomposition

MatrixDecomposition.Determinant<N extends java.lang.Comparable<N>>, MatrixDecomposition.EconomySize<N extends java.lang.Comparable<N>>, MatrixDecomposition.Factory<D extends MatrixDecomposition<?>>, MatrixDecomposition.Hermitian<N extends java.lang.Comparable<N>>, MatrixDecomposition.Ordered<N extends java.lang.Comparable<N>>, MatrixDecomposition.Pivoting<N extends java.lang.Comparable<N>>, MatrixDecomposition.RankRevealing<N extends java.lang.Comparable<N>>, MatrixDecomposition.Solver<N extends java.lang.Comparable<N>>, MatrixDecomposition.Updatable<N extends java.lang.Comparable<N>>, MatrixDecomposition.Values<N extends java.lang.Comparable<N>>

Nested classes/interfaces inherited from interface org.ojalgo.matrix.Provider2D

Provider2D.Condition, Provider2D.Determinant<N extends java.lang.Comparable<N>>, Provider2D.Eigenpairs, Provider2D.Hermitian, Provider2D.Inverse<M>, Provider2D.Rank, Provider2D.Solution<M>, Provider2D.Symmetric, Provider2D.Trace<N extends java.lang.Comparable<N>>

Nested classes/interfaces inherited from interface org.ojalgo.matrix.decomposition.SingularValue

SingularValue.Factory<N extends java.lang.Comparable<N>>

Nested classes/interfaces inherited from interface org.ojalgo.structure.Structure1D

Structure1D.BasicMapper<T>, Structure1D.IndexMapper<T>, Structure1D.IntIndex, Structure1D.LongIndex, Structure1D.LoopCallback

Nested classes/interfaces inherited from interface org.ojalgo.structure.Structure2D

Structure2D.IntRowColumn, Structure2D.Logical<S extends Structure2D,B extends Structure2D.Logical<S,B>>, Structure2D.LongRowColumn, Structure2D.ReducibleTo1D<R extends Structure1D>, Structure2D.Reshapable, Structure2D.RowColumnKey<R,C>, Structure2D.RowColumnMapper<R,C>

Field Summary

Fields

Modifier and Type	Field	Description
private double[]	e
private int	m	Calculation row and column dimensions, possibly transposed from the input
private MatrixStore<java.lang.Double>	myInverse
private boolean	myTransposed
private double[][]	myUt	Arrays for internal storage of U and V.
private double[][]	myVt
private int	n	Calculation row and column dimensions, possibly transposed from the input
private double[]	s	Array for internal storage of singular values.
private double[]	w

Fields inherited from interface org.ojalgo.matrix.decomposition.MatrixDecomposition

TYPICAL

Fields inherited from interface org.ojalgo.matrix.decomposition.SingularValue

C128, H256, Q128, R064, R128

Constructor Summary

Constructors

Constructor	Description
RawSingularValue()	Not recommended to use this constructor directly.

Method Summary

Modifier and Type	Method	Description
void	btran(double[] arg)
void	btran(PhysicalStore<java.lang.Double> arg)	Backwards-transformation
protected boolean	checkSolvability()
boolean	computeValuesOnly(Access2D.Collectable<java.lang.Double,? super TransformableRegion<java.lang.Double>> matrix)
int	countSignificant(double threshold)
boolean	decompose(Access2D.Collectable<java.lang.Double,? super TransformableRegion<java.lang.Double>> matrix)
(package private) boolean	doDecompose(Access2D.Collectable<java.lang.Double,? super PhysicalStore<java.lang.Double>> matrix, boolean factors)
void	ftran(double[] arg)
double	getCondition()	The condition number.
MatrixStore<java.lang.Double>	getCovariance()
MatrixStore<java.lang.Double>	getD()	Deprecated. Use getS() instead
double	getFrobeniusNorm()	Sometimes also called the Schatten 2-norm or Hilbert-Schmidt norm.
MatrixStore<java.lang.Double>	getInverse()	The output must be a "right inverse" and a "generalised inverse".
MatrixStore<java.lang.Double>	getInverse(PhysicalStore<java.lang.Double> preallocated)	Implementing this method is optional.
double	getKyFanNorm(int k)	Ky Fan k-norm.
double	getOperatorNorm()	Two norm
double	getRankThreshold()
MatrixStore<java.lang.Double>	getS()
Array1D<java.lang.Double>	getSingularValues()
void	getSingularValues(double[] values)
MatrixStore<java.lang.Double>	getSolution(Access2D.Collectable<java.lang.Double,? super PhysicalStore<java.lang.Double>> rhs, PhysicalStore<java.lang.Double> preallocated)	Implementing this method is optional.
double	getTraceNorm()
MatrixStore<java.lang.Double>	getU()	If [A] is m-by-n and its rank is r, then: The first r columns of [U] span the column space, range or image of [A]. The last m-r columns of [U] span the left nullspace or cokernel of [A]. Calculating the QR decomposition of [A] is a faster alternative.
MatrixStore<java.lang.Double>	getV()	If [A] is m-by-n and its rank is r, then: The first r columns of [V] span the row space or coimage of [A]. The last n-r columns of [V] span the nullspace or kernel of [A]. Calculating the QR decomposition of [A]T is a faster alternative.
MatrixStore<java.lang.Double>	invert(Access2D<?> original, PhysicalStore<java.lang.Double> preallocated)	Exactly how (if at all) a specific implementation makes use of preallocated is not specified by this interface.
boolean	isFullRank()
boolean	isFullSize()
boolean	isOrdered()	This is a property of the algorithm/implementation, not the data.
boolean	isSolvable()	Please note that producing a pseudoinverse and/or a least squares solution is ok! The return value, of this method, is not an indication of if the decomposed matrix is square, has full rank, is postive definite or whatever.
PhysicalStore<java.lang.Double>	preallocate(int nbEquations, int nbVariables, int nbSolutions)
void	reset()	Delete computed results, and resets attributes to default values
MatrixStore<java.lang.Double>	solve(Access2D<?> body, Access2D<?> rhs, PhysicalStore<java.lang.Double> preallocated)	Exactly how (if at all) a specific implementation makes use of preallocated is not specified by this interface.

Methods inherited from class org.ojalgo.matrix.decomposition.RawDecomposition

checkSymmetry, getColDim, getInternalData, getInternalStore, getRowDim, make, newRawStore, reset, wrap

Methods inherited from class org.ojalgo.matrix.decomposition.AbstractDecomposition

aggregator, applyPivotOrder, applyReverseOrder, collect, computed, copyColumn, copyRow, function, getDimensionalEpsilon, isAspectRatioNormal, isComputed, makeArray, makeDiagonal, makeEye, makeHouseholder, makeIdentity, makeRotation, makeRotation, makeZero, makeZero, scalar, wrap

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.ojalgo.matrix.task.InverterTask

invert, preallocate

Methods inherited from interface org.ojalgo.matrix.decomposition.MatrixDecomposition

isComputed

Methods inherited from interface org.ojalgo.matrix.decomposition.MatrixDecomposition.RankRevealing

getRank

Methods inherited from interface org.ojalgo.matrix.decomposition.MatrixDecomposition.Solver

compute, getSolution, invert, preallocate, solve, toInverseProvider, toSolutionProvider

Methods inherited from interface org.ojalgo.matrix.decomposition.SingularValue

ftran, reconstruct, reconstruct

Methods inherited from interface org.ojalgo.matrix.task.SolverTask

preallocate, solve

Methods inherited from interface org.ojalgo.structure.Structure2D

count, countColumns, countRows, firstInColumn, firstInRow, getColDim, getMaxDim, getMinDim, getRowDim, isEmpty, isFat, isScalar, isSquare, isTall, isVector, limitOfColumn, limitOfRow, size

Field Detail

e

private double[] e

m

private int m

Calculation row and column dimensions, possibly transposed from the input

n

private int n

Calculation row and column dimensions, possibly transposed from the input

myInverse

private transient MatrixStore<java.lang.Double> myInverse

myTransposed

private boolean myTransposed

myUt

private double[][] myUt

Arrays for internal storage of U and V.

myVt

private double[][] myVt

s

private double[] s

Array for internal storage of singular values.

w

private double[] w

Constructor Detail

RawSingularValue

RawSingularValue()

Not recommended to use this constructor directly. Consider using the static factory method org.ojalgo.matrix.decomposition.SingularValue#make(Access2D) instead.

Method Detail

btran

public void btran(double[] arg)

Specified by:

btran in interface InvertibleFactor<java.lang.Double>

See Also:

InvertibleFactor.IdentityFactor.btran(PhysicalStore)

btran

public void btran(PhysicalStore<java.lang.Double> arg)

Description copied from interface: InvertibleFactor

Backwards-transformation

Solve [x]^T[A] = [b]^T (equivalent to [A]^T[x] = [b]) by transforming [b] into [x] in-place.

Specified by:

btran in interface InvertibleFactor<java.lang.Double>

Parameters:

arg - [b] transformed into [x]

computeValuesOnly

public boolean computeValuesOnly(Access2D.Collectable<java.lang.Double,? super TransformableRegion<java.lang.Double>> matrix)

Specified by:

computeValuesOnly in interface MatrixDecomposition.Values<java.lang.Double>

Parameters:

matrix - The matrix to decompose

Returns:

The same as MatrixDecomposition.Solver.compute(Collectable) or MatrixDecomposition.decompose(Collectable) if the instance does not implement MatrixDecomposition.Solver.

countSignificant

public int countSignificant(double threshold)

Specified by:

countSignificant in interface MatrixDecomposition.RankRevealing<java.lang.Double>

Parameters:

threshold - Significance limit

Returns:

The number of elements in the diagonal matrix that are greater than the threshold

decompose

public boolean decompose(Access2D.Collectable<java.lang.Double,? super TransformableRegion<java.lang.Double>> matrix)

Specified by:

decompose in interface MatrixDecomposition<java.lang.Double>

Parameters:

matrix - A matrix to decompose

Returns:

true if decomposition suceeded; false if not

ftran

public void ftran(double[] arg)

Specified by:

ftran in interface InvertibleFactor<java.lang.Double>

See Also:

InvertibleFactor.IdentityFactor.ftran(PhysicalStore)

getCondition

public double getCondition()

Description copied from interface: SingularValue

The condition number.

Specified by:

getCondition in interface Provider2D.Condition

Specified by:

getCondition in interface SingularValue<java.lang.Double>

Returns:

The largest singular value divided by the smallest singular value.

getCovariance

public MatrixStore<java.lang.Double> getCovariance()

Specified by:

getCovariance in interface SingularValue<java.lang.Double>

Returns:

[[A]^T[A]]^-1 Where [A] is the original matrix.

getD

@Deprecated
public MatrixStore<java.lang.Double> getD()

Deprecated.

Use getS() instead

Specified by:

getD in interface SingularValue<java.lang.Double>

Returns:

The diagonal matrix of singular values.

getFrobeniusNorm

public double getFrobeniusNorm()

Description copied from interface: SingularValue

Sometimes also called the Schatten 2-norm or Hilbert-Schmidt norm.

Specified by:

getFrobeniusNorm in interface SingularValue<java.lang.Double>

Returns:

The square root of the sum of squares of the singular values.

getInverse

public MatrixStore<java.lang.Double> getInverse()

Description copied from interface: MatrixDecomposition.Solver

The output must be a "right inverse" and a "generalised inverse".

Specified by:

getInverse in interface MatrixDecomposition.Solver<java.lang.Double>

getInverse

public MatrixStore<java.lang.Double> getInverse(PhysicalStore<java.lang.Double> preallocated)

Description copied from interface: MatrixDecomposition.Solver

Implementing this method is optional.

Exactly how a specific implementation makes use of preallocated is not specified by this interface. It must be documented for each implementation.

Should produce the same results as calling MatrixDecomposition.Solver.getInverse().

Specified by:

getInverse in interface MatrixDecomposition.Solver<java.lang.Double>

Parameters:

preallocated - Preallocated memory for the results, possibly some intermediate results. You must assume this is modified, but you cannot assume it will contain the full/final/correct solution. Use MatrixDecomposition.Solver.preallocate(int, int) or InverterTask.preallocate(Structure2D) to get a suitable instance.

Returns:

The inverse, this is where you get the solution

getKyFanNorm

public double getKyFanNorm(int k)

Description copied from interface: SingularValue

Ky Fan k-norm.

The first Ky Fan k-norm is the operator norm (the largest singular value), and the last is called the trace norm (the sum of all singular values).

Specified by:

getKyFanNorm in interface SingularValue<java.lang.Double>

Parameters:

k - The number of singular values to add up.

Returns:

The sum of the k largest singular values.

getOperatorNorm

public double getOperatorNorm()

Two norm

Specified by:

getOperatorNorm in interface SingularValue<java.lang.Double>

Returns:

max(S)

getRankThreshold

public double getRankThreshold()

Specified by:

getRankThreshold in interface MatrixDecomposition.RankRevealing<java.lang.Double>

getS

public MatrixStore<java.lang.Double> getS()

Specified by:

getS in interface SingularValue<java.lang.Double>

Returns:

The diagonal matrix of singular values.

getSingularValues

public Array1D<java.lang.Double> getSingularValues()

Specified by:

getSingularValues in interface SingularValue<java.lang.Double>

Returns:

The singular values ordered in descending order.

getSingularValues

public void getSingularValues(double[] values)

Specified by:

getSingularValues in interface SingularValue<java.lang.Double>

Parameters:

values - An array that will receive the singular values

getSolution

public MatrixStore<java.lang.Double> getSolution(Access2D.Collectable<java.lang.Double,? super PhysicalStore<java.lang.Double>> rhs,
                                                 PhysicalStore<java.lang.Double> preallocated)

Description copied from interface: MatrixDecomposition.Solver

Implementing this method is optional.

Exactly how a specific implementation makes use of preallocated is not specified by this interface. It must be documented for each implementation.

Should produce the same results as calling MatrixDecomposition.Solver.getSolution(Collectable).

Specified by:

getSolution in interface MatrixDecomposition.Solver<java.lang.Double>

Parameters:

rhs - The Right Hand Side, wont be modfied

preallocated - Preallocated memory for the results, possibly some intermediate results. You must assume this is modified, but you cannot assume it will contain the full/final/correct solution. Use SolverTask.preallocate(int, int, int) or SolverTask.preallocate(Structure2D, Structure2D) to get a suitable instance.

Returns:

The solution

getTraceNorm

public double getTraceNorm()

Specified by:

getTraceNorm in interface SingularValue<java.lang.Double>

getU

public MatrixStore<java.lang.Double> getU()

Description copied from interface: SingularValue

If [A] is m-by-n and its rank is r, then:

• The first r columns of [U] span the column space, range or image of [A].
• The last m-r columns of [U] span the left nullspace or cokernel of [A].

Calculating the QR decomposition of [A] is a faster alternative.

Specified by:

getU in interface SingularValue<java.lang.Double>

getV

public MatrixStore<java.lang.Double> getV()

Description copied from interface: SingularValue

If [A] is m-by-n and its rank is r, then:

• The first r columns of [V] span the row space or coimage of [A].
• The last n-r columns of [V] span the nullspace or kernel of [A].

Calculating the QR decomposition of [A]^T is a faster alternative.

Specified by:

getV in interface SingularValue<java.lang.Double>

invert

public MatrixStore<java.lang.Double> invert(Access2D<?> original,
                                            PhysicalStore<java.lang.Double> preallocated)
                                     throws RecoverableCondition

Description copied from interface: InverterTask

Exactly how (if at all) a specific implementation makes use of preallocated is not specified by this interface. It must be documented for each implementation.

Should produce the same results as calling InverterTask.invert(Access2D).

Use InverterTask.preallocate(Structure2D) to obtain a suitbale preallocated.

Specified by:

invert in interface InverterTask<java.lang.Double>

preallocated - Preallocated memory for the results, possibly some intermediate results. You must assume this is modified, but you cannot assume it will contain the full/final/correct solution.

Returns:

The inverse

Throws:

RecoverableCondition - TODO

isFullRank

public boolean isFullRank()

Specified by:

isFullRank in interface MatrixDecomposition.RankRevealing<java.lang.Double>

Returns:

true if the rank is equal to the minimum of the row and column dimensions; false if not

isFullSize

public boolean isFullSize()

Specified by:

isFullSize in interface MatrixDecomposition.EconomySize<java.lang.Double>

Returns:

True if it will generate a full sized decomposition.

isOrdered

public boolean isOrdered()

Description copied from interface: MatrixDecomposition.Ordered

This is a property of the algorithm/implementation, not the data. Typically relevant for SingularValue, Eigenvalue or any MatrixDecomposition.RankRevealing decomposition.

Specified by:

isOrdered in interface MatrixDecomposition.Ordered<java.lang.Double>

Returns:

true if the rows/columns of the returned matrix factors are guaranteed some specific order; false if there is no such guarantee.

isSolvable

public boolean isSolvable()

Description copied from interface: MatrixDecomposition.Solver

Please note that producing a pseudoinverse and/or a least squares solution is ok! The return value, of this method, is not an indication of if the decomposed matrix is square, has full rank, is postive definite or whatever. It's that in combination with the specific decomposition algorithm's capabilities.

Specified by:

isSolvable in interface MatrixDecomposition.Solver<java.lang.Double>

Overrides:

isSolvable in class AbstractDecomposition<java.lang.Double,R064Store>

Returns:

true if this matrix decomposition is in a state to be able to deliver an inverse or an equation system solution (with some degree of numerical stability).

preallocate

public PhysicalStore<java.lang.Double> preallocate(int nbEquations,
                                                   int nbVariables,
                                                   int nbSolutions)

Specified by:

preallocate in interface SolverTask<java.lang.Double>

reset

public void reset()

Description copied from interface: MatrixDecomposition

Delete computed results, and resets attributes to default values

Specified by:

reset in interface MatrixDecomposition<java.lang.Double>

Overrides:

reset in class AbstractDecomposition<java.lang.Double,R064Store>

solve

public MatrixStore<java.lang.Double> solve(Access2D<?> body,
                                           Access2D<?> rhs,
                                           PhysicalStore<java.lang.Double> preallocated)
                                    throws RecoverableCondition

Description copied from interface: SolverTask

Exactly how (if at all) a specific implementation makes use of preallocated is not specified by this interface. It must be documented for each implementation.

Should produce the same results as calling SolverTask.solve(Access2D, Access2D).

Use SolverTask.preallocate(Structure2D, Structure2D) to obtain a suitbale preallocated.

Specified by:

solve in interface SolverTask<java.lang.Double>

rhs - The Right Hand Side, wont be modfied

preallocated - Preallocated memory for the results, possibly some intermediate results. You must assume this is modified, but you cannot assume it will contain the full/ /correct solution.

Returns:

The solution

Throws:

RecoverableCondition

checkSolvability

protected boolean checkSolvability()

Overrides:

checkSolvability in class AbstractDecomposition<java.lang.Double,R064Store>

doDecompose

boolean doDecompose(Access2D.Collectable<java.lang.Double,? super PhysicalStore<java.lang.Double>> matrix,
                    boolean factors)