org.ejml.alg.dense.decomposition
Class DecompositionFactory

java.lang.Object
  org.ejml.alg.dense.decomposition.DecompositionFactory

public class DecompositionFactory
extends Object

Contains operations related to creating and evaluating the quality of common matrix decompositions.

In general this is the best place to create matrix decompositions from since directly calling the algorithm is error prone since it require in depth knowledge of how the algorithm operators. The exact implementations created is subject to change as newer, faster and more accurate implementations are added.

Several functions are also provided to evaluate the quality of a decomposition. This is provided as a way to sanity check a decomposition. Often times a significant error in a decomposition will result in a poor (larger) quality value. Typically a quality value of around 1e-15 means it is within machine precision.

Author:

Peter Abeles

Constructor Summary

DecompositionFactory()

Method Summary

static CholeskyDecomposition<DenseMatrix64F>	chol(int widthWidth, boolean lower) If you don't know which Cholesky algorithm to use, call this function to select what is most likely the best one for you.
static CholeskyDecompositionLDL	cholLDL(int matrixWidth) Creates a CholeskyDecompositionLDL decomposition.
static <T extends Matrix64F> boolean	decomposeSafe(DecompositionInterface<T> decomp, T M) Makes sure the decomposed matrix is not modified.
static EigenDecomposition<DenseMatrix64F>	eig(int matrixWidth) Returns a new eigenvalue decomposition.
static EigenDecomposition<DenseMatrix64F>	eig(int matrixWidth, boolean needVectors) Same as eig(int) but can turn on and off computing eigen vectors
static EigenDecomposition<DenseMatrix64F>	eigGeneral(int matrixSize, boolean computeVectors) Creates a new EigenDecomposition that will work with any matrix.
static EigenDecomposition<DenseMatrix64F>	eigSymm(int matrixWidth, boolean computeVectors) Creates a new EigenDecomposition that will only work with symmetric matrices.
static LUDecomposition<DenseMatrix64F>	lu(int matrixWidth) Returns a new instance of the Lower Upper (LU) decomposition.
static QRDecomposition<DenseMatrix64F>	qr(int numRows, int numCols) Returns a new instance of the QR decomposition.
static QRPDecomposition<DenseMatrix64F>	qrp(int numRows, int numCols) Returns a new instance of QR decomposition with column pivoting. A*P = Q*R where A is the input matrix, and P is the pivot matrix.
static double	quality(DenseMatrix64F orig, DenseMatrix64F U, DenseMatrix64F W, DenseMatrix64F Vt)
static double	quality(DenseMatrix64F orig, EigenDecomposition<DenseMatrix64F> eig) Computes a metric which measures the the quality of an eigen value decomposition.
static double	quality(DenseMatrix64F orig, SingularValueDecomposition<DenseMatrix64F> svd) Computes a metric which measures the the quality of a singular value decomposition.
static SingularValueDecomposition<DenseMatrix64F>	svd(int numRows, int numCols) Returns a new instance of a SingularValueDecomposition which will compute the full decomposition..
static SingularValueDecomposition<DenseMatrix64F>	svd(int numRows, int numCols, boolean needU, boolean needV, boolean compact) Returns a new instance of a SingularValueDecomposition which can be configured to compute U and V matrices or not, be in compact form.
static TridiagonalSimilarDecomposition<DenseMatrix64F>	tridiagonal(int matrixWidth) Checks to see if the passed in tridiagonal decomposition is of the appropriate type for the matrix of the provided size.

Methods inherited from class java.lang.Object

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

Constructor Detail

DecompositionFactory

public DecompositionFactory()

Method Detail

chol

public static CholeskyDecomposition<DenseMatrix64F> chol(int widthWidth,
                                                         boolean lower)

If you don't know which Cholesky algorithm to use, call this function to select what is most likely the best one for you.

Creates a new instance of a CholeskyDecomposition algorithm. It selects the best algorithm depending on the size of the largest matrix it might decompose.

Parameters:

widthWidth - The matrix size that the decomposition should be optimized for.

lower - should a lower or upper triangular matrix be used.

Returns:

A new CholeskyDecomposition.

cholLDL

public static CholeskyDecompositionLDL cholLDL(int matrixWidth)

Creates a CholeskyDecompositionLDL decomposition. Cholesky LDL is a variant of CholeskyDecomposition that avoids need to compute the square root.

Parameters:

matrixWidth - The matrix size that the decomposition should be optimized for.

Returns:

CholeskyDecompositionLDL

lu

public static LUDecomposition<DenseMatrix64F> lu(int matrixWidth)

Returns a new instance of the Lower Upper (LU) decomposition.

Returns:

LUDecomposition

svd

public static SingularValueDecomposition<DenseMatrix64F> svd(int numRows,
                                                             int numCols)

Returns a new instance of a SingularValueDecomposition which will compute the full decomposition..

Parameters:

numRows - The number of rows that the decomposition is optimized for.

numCols - The number of columns that the decomposition is optimized for.

Returns:

SingularValueDecomposition

svd

public static SingularValueDecomposition<DenseMatrix64F> svd(int numRows,
                                                             int numCols,
                                                             boolean needU,
                                                             boolean needV,
                                                             boolean compact)

Returns a new instance of a SingularValueDecomposition which can be configured to compute U and V matrices or not, be in compact form.

Parameters:

numRows - The number of rows that the decomposition is optimized for.

numCols - The number of columns that the decomposition is optimized for.

needU - Should it compute the U matrix.

needV - Should it compute the V matrix.

compact - Should it compute the SVD in compact form.

Returns:

qr

public static QRDecomposition<DenseMatrix64F> qr(int numRows,
                                                 int numCols)

Returns a new instance of the QR decomposition.

Parameters:

numRows - The number of rows that the decomposition is optimized for.

numCols - The number of columns that the decomposition is optimized for.

Returns:

QRDecomposition

qrp

public static QRPDecomposition<DenseMatrix64F> qrp(int numRows,
                                                   int numCols)

Returns a new instance of QR decomposition with column pivoting.
A*P = Q*R
where A is the input matrix, and P is the pivot matrix.

Parameters:

numRows - The number of rows that the decomposition is optimized for.

numCols - The number of columns that the decomposition is optimized for.

Returns:

QRPDecomposition

eig

public static EigenDecomposition<DenseMatrix64F> eig(int matrixWidth)

Returns a new eigenvalue decomposition. If it is known before hand if the matrix is symmetric or not then a call should be made directly to either eigGeneral(int,boolean) or eigSymm(int, boolean). That will avoid unnecessary checks.

Parameters:

matrixWidth - The matrix size that the decomposition should be optimized for.

Returns:

A new EigenDecomposition.

eig

public static EigenDecomposition<DenseMatrix64F> eig(int matrixWidth,
                                                     boolean needVectors)

Same as eig(int) but can turn on and off computing eigen vectors

Parameters:

matrixWidth - The matrix size that the decomposition should be optimized for.

needVectors - Should eigenvectors be computed or not.

Returns:

A new EigenDecomposition

eigGeneral

public static EigenDecomposition<DenseMatrix64F> eigGeneral(int matrixSize,
                                                            boolean computeVectors)

Creates a new EigenDecomposition that will work with any matrix.

Parameters:

computeVectors - Should it compute the eigenvectors or just eigenvalues.

Returns:

EVD for any matrix.

eigSymm

public static EigenDecomposition<DenseMatrix64F> eigSymm(int matrixWidth,
                                                         boolean computeVectors)

Creates a new EigenDecomposition that will only work with symmetric matrices. This will run much faster and be more accurate than the general purpose algorithm.

Parameters:

matrixWidth - The number of rows/columns in the matrix. Used to select the best algorithms.

computeVectors - Should it compute the eigenvectors or just eigenvalues.

Returns:

EVD for symmetric matrices.

quality

public static double quality(DenseMatrix64F orig,
                             SingularValueDecomposition<DenseMatrix64F> svd)

Computes a metric which measures the the quality of a singular value decomposition. If a value is returned that is close to or smaller than 1e-15 then it is within machine precision.

SVD quality is defined as:

Quality = || A - U W V^T|| / || A ||
where A is the original matrix , U W V is the decomposition, and ||A|| is the norm-f of A.

Parameters:

orig - The original matrix which was decomposed. Not modified.

svd - The decomposition after processing 'orig'. Not modified.

Returns:

The quality of the decomposition.

quality

public static double quality(DenseMatrix64F orig,
                             DenseMatrix64F U,
                             DenseMatrix64F W,
                             DenseMatrix64F Vt)

quality

public static double quality(DenseMatrix64F orig,
                             EigenDecomposition<DenseMatrix64F> eig)

Computes a metric which measures the the quality of an eigen value decomposition. If a value is returned that is close to or smaller than 1e-15 then it is within machine precision.

EVD quality is defined as:

Quality = ||A*V - V*D|| / ||A*V||.

Parameters:

orig - The original matrix. Not modified.

eig - EVD of the original matrix. Not modified.

Returns:

The quality of the decomposition.

tridiagonal

public static TridiagonalSimilarDecomposition<DenseMatrix64F> tridiagonal(int matrixWidth)

Checks to see if the passed in tridiagonal decomposition is of the appropriate type for the matrix of the provided size. Returns the same instance or a new instance.

decomposeSafe

public static <T extends Matrix64F> boolean decomposeSafe(DecompositionInterface<T> decomp,
                                                          T M)

Makes sure the decomposed matrix is not modified.

Type Parameters:

T -

Parameters:

decomp -

M -

Returns: