Class LinearAlgebra

java.lang.Object

net.finmath.functions.LinearAlgebra

public class LinearAlgebra
extends Object

This class implements some methods from linear algebra (e.g. solution of a linear equation, PCA). It is basically a functional wrapper using either Apache Commons Math, EJML or JBlas

Version:

1.6

Author:

Christian Fries

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	LinearAlgebra.Solver	Immutable backend-specific solver facade.
static enum	LinearAlgebra.SolverBackend

Constructor Summary

Constructors

Constructor	Description
LinearAlgebra()

Method Summary

Modifier and Type	Method	Description
static double[][]	diag(double[] vector)	Generates a diagonal matrix with the input vector on its diagonal
static double[][]	exp(double[][] matrix)	Calculate the "matrix exponential" (expm).
static org.apache.commons.math3.linear.RealMatrix	exp(org.apache.commons.math3.linear.RealMatrix matrix)	Calculate the "matrix exponential" (expm).
static double[][]	factorReduction(double[][] correlationMatrix, int numberOfFactors)	Returns a correlation matrix which has rank < n and for which the first n factors agree with the factors of correlationMatrix.
static double[][]	factorReductionUsingCommonsMath(double[][] correlationMatrix, int numberOfFactors)	Returns a correlation matrix which has rank < n and for which the first n factors agree with the factors of correlationMatrix.
static double[][]	getCholeskyDecomposition(double[][] symmetricMatrix)	Create a Cholesky decomposition of a symmetric matrix.
static LinearAlgebra.Solver	getDefaultSolver()	Creates a solver instance using the default backend.
static LinearAlgebra.SolverBackend	getDefaultSolverBackend()	Returns the immutable default backend used by the static solve methods.
static double[][]	getFactorMatrix(double[][] correlationMatrix, int numberOfFactors)	Returns the matrix of the n Eigenvectors corresponding to the first n largest Eigenvalues of a correlation matrix.
static LinearAlgebra.Solver	getSolver(LinearAlgebra.SolverBackend solverBackend)	Creates a backend-specific, immutable solver instance.
static LinearAlgebra.SolverBackend	getSolverBackend()	Returns the immutable default backend used by the static solve methods.
static double[][]	invert(double[][] matrix)	Returns the inverse of a given matrix.
static double[][]	invert(LinearAlgebra.SolverBackend solverBackend, double[][] matrix)
static boolean	isEigenvalueDecompositionViaSVD()
static boolean	isJBlasAvailable()
static boolean	isSolverUseApacheCommonsMath()	Returns the legacy solver flag.
static double[][]	matrixExp(double[][] matrix)	Matrix exponential.
static boolean	matrixIsColZero(double[][] matrix, int i)
static boolean	matrixIsRowZero(double[][] matrix, int i)
static double[][]	matrixLog(double[][] matrix)	Matrix logarithm.
static double	matrixNormFrobeniusSquared(double[][] matrix)	Matrix Frobenius norm squared ||M||^2.
static double[][]	matrixPow(double[][] matrix, double exponent)	Matrix power.
static double	matrixTrace(double[][] matrix)	Matrix trace tr(M).
static double[][]	multMatrices(double[][] left, double[][] right)	Multiplication of two matrices.
static double[]	multMatrixVector(double[][] matrix, double[] vector)	Multiplication of matrix and vector.
static LinearAlgebra.Solver	of(LinearAlgebra.SolverBackend solverBackend)	Creates a backend-specific, immutable solver instance.
static double[][]	pow(double[][] matrix, double exponent)	Calculate the power of a matrix Note: The function currently requires jblas.
static double[][]	pseudoInverse(double[][] matrix)	Pseudo-Inverse of a matrix calculated in the least square sense.
static double[][]	pseudoInverse(LinearAlgebra.SolverBackend solverBackend, double[][] matrix)
static double[]	solveLinearEquation(double[][] matrixA, double[] b)	Find a solution of the linear equation A x = b where A is an m x n - matrix given as double[m][n] b is an m - vector given as double[m], x is an n - vector given as double[n],
static double[]	solveLinearEquation(LinearAlgebra.SolverBackend solverBackend, double[][] matrixA, double[] b)
static double[]	solveLinearEquationCholesky(double[][] matrix, double[] rhs)
static double[]	solveLinearEquationCholesky(LinearAlgebra.SolverBackend solverBackend, double[][] matrix, double[] rhs)
static double[]	solveLinearEquationLeastSquare(double[][] matrix, double[] vector)	Find a solution of the linear equation A x = b in the least square sense where A is an m x n - matrix given as double[m][n] b is an m - vector given as double[m], x is an n - vector given as double[n], If the least-squares solution is not unique, the solution with minimum Euclidean norm is returned.
static double[][]	solveLinearEquationLeastSquare(double[][] matrix, double[][] rhs)	Find a solution of the linear equation A X = B in the least square sense where A is an m x n - matrix given as double[m][n] B is an m x k - matrix given as double[m][k], X is an n x k - matrix given as double[n][k], If a least-squares solution is not unique, each right-hand side is solved using the minimum-Euclidean-norm solution.
static double[]	solveLinearEquationLeastSquare(LinearAlgebra.SolverBackend solverBackend, double[][] matrix, double[] vector)
static double[][]	solveLinearEquationLeastSquare(LinearAlgebra.SolverBackend solverBackend, double[][] matrix, double[][] rhs)
static double[]	solveLinearEquationSVD(double[][] matrixA, double[] b)	Find a solution of the linear equation A x = b where A is an m x n - matrix given as double[m][n] b is an m - vector given as double[m], x is an n - vector given as double[n],
static double[]	solveLinearEquationSVD(LinearAlgebra.SolverBackend solverBackend, double[][] matrixA, double[] b)
static double[]	solveLinearEquationSymmetric(double[][] matrix, double[] vector)	Find a solution of the linear equation A x = b where A is an symmetric n x n - matrix given as double[n][n] b is an n - vector given as double[n], x is an n - vector given as double[n],
static double[]	solveLinearEquationSymmetric(LinearAlgebra.SolverBackend solverBackend, double[][] matrix, double[] vector)
static double[]	solveLinearEquationTikonov(double[][] matrixA, double[] b, double lambda)	Find a solution of the linear equation A x = b where A is an m x n - matrix given as double[m][n] b is an m - vector given as double[m], x is an n - vector given as double[n], using a standard Tikhonov regularization, i.e., we solve in the least square sense A* x = b* where A* = (A^T, lambda I)^T and b* = (b^T , 0)^T.
static double[]	solveLinearEquationTikonov(double[][] matrixA, double[] b, double lambda0, double lambda1, double lambda2)	Find a solution of the linear equation A x = b where A is an m x n - matrix given as double[m][n] b is an m - vector given as double[m], x is an n - vector given as double[n], using a Tikhonov regularization, i.e., we solve in the least square sense A* x = b* where A* = (A^T, lambda0 I, lambda1 S, lambda2 C)^T and b* = (b^T , 0 , 0 , 0)^T.
static double[]	solveLinearEquationTikonov(LinearAlgebra.SolverBackend solverBackend, double[][] matrixA, double[] b, double lambda)
static double[]	solveLinearEquationTikonov(LinearAlgebra.SolverBackend solverBackend, double[][] matrixA, double[] b, double lambda0, double lambda1, double lambda2)
static double[]	solveTikhonovViaNormalEquations(double[][] matrix, double[] rhs, double regularizationLambda)	Solves the Tikhonov-regularized normal equations
static double[]	solveTikhonovViaNormalEquations(LinearAlgebra.SolverBackend solverBackend, double[][] matrix, double[] rhs, double regularizationLambda)	Solves the Tikhonov-regularized normal equations using an explicit backend.
static double[][]	transpose(double[][] matrix)	Transpose a matrix

Methods inherited from class Object

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

Constructor Details

LinearAlgebra

public LinearAlgebra()

Method Details

isEigenvalueDecompositionViaSVD

public static boolean isEigenvalueDecompositionViaSVD()

isSolverUseApacheCommonsMath

public static boolean isSolverUseApacheCommonsMath()

Returns the legacy solver flag. This method is kept for backward compatibility and returns false only if the default backend is jblas. In particular, it returns true for EJML, since methods not converted to the backend enum continue to use Commons Math.

Returns:

True if the default solver backend is not jblas.

isJBlasAvailable

public static boolean isJBlasAvailable()

getSolverBackend

public static LinearAlgebra.SolverBackend getSolverBackend()

Returns the immutable default backend used by the static solve methods. The value is determined once during class initialization from system properties.

Returns:

The default solver backend.

getDefaultSolverBackend

public static LinearAlgebra.SolverBackend getDefaultSolverBackend()

Returns the immutable default backend used by the static solve methods.

Returns:

The default solver backend.

getSolver

public static LinearAlgebra.Solver getSolver(LinearAlgebra.SolverBackend solverBackend)

Creates a backend-specific, immutable solver instance. Use this if different parts of an application should use different solver backends without changing global static state.

Parameters:

solverBackend - The solver backend.

Returns:

A backend-specific solver instance.

of

public static LinearAlgebra.Solver of(LinearAlgebra.SolverBackend solverBackend)

Creates a backend-specific, immutable solver instance.

Parameters:

solverBackend - The solver backend.

Returns:

A backend-specific solver instance.

getDefaultSolver

public static LinearAlgebra.Solver getDefaultSolver()

Creates a solver instance using the default backend.

Returns:

A solver instance using the default backend.

getCholeskyDecomposition

public static double[][] getCholeskyDecomposition(double[][] symmetricMatrix)

Create a Cholesky decomposition of a symmetric matrix.

Parameters:

symmetricMatrix - The input matrix.

Returns:

A lower triangle matrix representing the CholeskyDecomposition.

solveLinearEquationTikonov

public static double[] solveLinearEquationTikonov(double[][] matrixA,
 double[] b,
 double lambda)

Find a solution of the linear equation A x = b where

• A is an m x n - matrix given as double[m][n]
• b is an m - vector given as double[m],
• x is an n - vector given as double[n],

using a standard Tikhonov regularization, i.e., we solve in the least square sense A* x = b* where A* = (A^T, lambda I)^T and b* = (b^T , 0)^T.

Parameters:

matrixA - The matrix A (left hand side of the linear equation).

b - The vector (right hand of the linear equation).

lambda - The parameter lambda of the Tikhonov regularization. Lambda effectively measures which small numbers are considered zero.

Returns:

A solution x to A x = b.

solveLinearEquationTikonov

public static double[] solveLinearEquationTikonov(LinearAlgebra.SolverBackend solverBackend,
 double[][] matrixA,
 double[] b,
 double lambda)

solveLinearEquationTikonov

public static double[] solveLinearEquationTikonov(double[][] matrixA,
 double[] b,
 double lambda0,
 double lambda1,
 double lambda2)

Find a solution of the linear equation A x = b where

• A is an m x n - matrix given as double[m][n]
• b is an m - vector given as double[m],
• x is an n - vector given as double[n],

using a Tikhonov regularization, i.e., we solve in the least square sense A* x = b* where A* = (A^T, lambda0 I, lambda1 S, lambda2 C)^T and b* = (b^T , 0 , 0 , 0)^T. The matrix I is the identity matrix, effectively reducing the level of the solution vector. The matrix S is the first order central finite difference matrix with -lambda1 on the element [i][i-1] and +lambda1 on the element [i][i+1] The matrix C is the second order central finite difference matrix with -0.5 lambda2 on the element [i][i-1] and [i][i+1] and lambda2 on the element [i][i].

Parameters:

matrixA - The matrix A (left hand side of the linear equation).

b - The vector (right hand of the linear equation).

lambda0 - The parameter lambda0 of the Tikhonov regularization. Reduces the norm of the solution vector.

lambda1 - The parameter lambda1 of the Tikhonov regularization. Reduces the slope of the solution vector.

lambda2 - The parameter lambda1 of the Tikhonov regularization. Reduces the curvature of the solution vector.

Returns:

The solution x of the equation A* x = b*

solveLinearEquationTikonov

public static double[] solveLinearEquationTikonov(LinearAlgebra.SolverBackend solverBackend,
 double[][] matrixA,
 double[] b,
 double lambda0,
 double lambda1,
 double lambda2)

solveLinearEquation

public static double[] solveLinearEquation(double[][] matrixA,
 double[] b)

Find a solution of the linear equation A x = b where

• A is an m x n - matrix given as double[m][n]
• b is an m - vector given as double[m],
• x is an n - vector given as double[n],

Parameters:

matrixA - The matrix A (left hand side of the linear equation).

b - The vector (right hand of the linear equation).

Returns:

A solution x to A x = b.

solveLinearEquation

public static double[] solveLinearEquation(LinearAlgebra.SolverBackend solverBackend,
 double[][] matrixA,
 double[] b)

solveLinearEquationSVD

public static double[] solveLinearEquationSVD(double[][] matrixA,
 double[] b)

Find a solution of the linear equation A x = b where

• A is an m x n - matrix given as double[m][n]
• b is an m - vector given as double[m],
• x is an n - vector given as double[n],

Parameters:

matrixA - The matrix A (left hand side of the linear equation).

b - The vector (right hand of the linear equation).

Returns:

A solution x to A x = b.

solveLinearEquationSVD

public static double[] solveLinearEquationSVD(LinearAlgebra.SolverBackend solverBackend,
 double[][] matrixA,
 double[] b)

invert

public static double[][] invert(double[][] matrix)

Returns the inverse of a given matrix.

Parameters:

matrix - A matrix given as double[n][n].

Returns:

The inverse of the given matrix.

invert

public static double[][] invert(LinearAlgebra.SolverBackend solverBackend,
 double[][] matrix)

solveLinearEquationSymmetric

public static double[] solveLinearEquationSymmetric(double[][] matrix,
 double[] vector)

Find a solution of the linear equation A x = b where

• A is an symmetric n x n - matrix given as double[n][n]
• b is an n - vector given as double[n],
• x is an n - vector given as double[n],

Parameters:

matrix - The matrix A (left hand side of the linear equation).

vector - The vector b (right hand of the linear equation).

Returns:

A solution x to A x = b.

solveLinearEquationSymmetric

public static double[] solveLinearEquationSymmetric(LinearAlgebra.SolverBackend solverBackend,
 double[][] matrix,
 double[] vector)

solveLinearEquationLeastSquare

public static double[] solveLinearEquationLeastSquare(double[][] matrix,
 double[] vector)

Find a solution of the linear equation A x = b in the least square sense where

• A is an m x n - matrix given as double[m][n]
• b is an m - vector given as double[m],
• x is an n - vector given as double[n],

If the least-squares solution is not unique, the solution with minimum Euclidean norm is returned.

Parameters:

matrix - The matrix A (left hand side of the linear equation).

vector - The vector b (right hand of the linear equation).

Returns:

A solution x to A x = b.

solveLinearEquationLeastSquare

public static double[] solveLinearEquationLeastSquare(LinearAlgebra.SolverBackend solverBackend,
 double[][] matrix,
 double[] vector)

solveLinearEquationLeastSquare

public static double[][] solveLinearEquationLeastSquare(double[][] matrix,
 double[][] rhs)

Find a solution of the linear equation A X = B in the least square sense where

• A is an m x n - matrix given as double[m][n]
• B is an m x k - matrix given as double[m][k],
• X is an n x k - matrix given as double[n][k],

If a least-squares solution is not unique, each right-hand side is solved using the minimum-Euclidean-norm solution.

Parameters:

matrix - The matrix A (left hand side of the linear equation).

rhs - The matrix B (right hand of the linear equation).

Returns:

A solution X to A X = B.

solveLinearEquationLeastSquare

public static double[][] solveLinearEquationLeastSquare(LinearAlgebra.SolverBackend solverBackend,
 double[][] matrix,
 double[][] rhs)

getFactorMatrix

public static double[][] getFactorMatrix(double[][] correlationMatrix,
 int numberOfFactors)

Returns the matrix of the n Eigenvectors corresponding to the first n largest Eigenvalues of a correlation matrix. These Eigenvectors can also be interpreted as "principal components" (i.e., the method implements the PCA).

Parameters:

correlationMatrix - The given correlation matrix.

numberOfFactors - The requested number of factors (eigenvectors).

Returns:

Matrix of n Eigenvectors (columns) (matrix is given as double[n][numberOfFactors], where n is the number of rows of the correlationMatrix.

factorReduction

public static double[][] factorReduction(double[][] correlationMatrix,
 int numberOfFactors)

Returns a correlation matrix which has rank < n and for which the first n factors agree with the factors of correlationMatrix.

Parameters:

correlationMatrix - The given correlation matrix.

numberOfFactors - The requested number of factors (Eigenvectors).

Returns:

Factor reduced correlation matrix.

factorReductionUsingCommonsMath

public static double[][] factorReductionUsingCommonsMath(double[][] correlationMatrix,
 int numberOfFactors)

Returns a correlation matrix which has rank < n and for which the first n factors agree with the factors of correlationMatrix.

Parameters:

correlationMatrix - The given correlation matrix.

numberOfFactors - The requested number of factors (Eigenvectors).

Returns:

Factor reduced correlation matrix.

exp

public static double[][] exp(double[][] matrix)

Calculate the "matrix exponential" (expm). Note: The function currently requires jblas. If jblas is not availabe on your system, an exception will be thrown. A future version of this function may implement a fall back.

Parameters:

matrix - The given matrix.

Returns:

The exp(matrix).

pow

public static double[][] pow(double[][] matrix,
 double exponent)

Calculate the power of a matrix Note: The function currently requires jblas. If jblas is not availabe on your system, an exception will be thrown. A future version of this function may implement a fall back.

Parameters:

matrix - The given matrix.

exponent - The exponent

Returns:

The pow(matrix, exponent).

exp

public static org.apache.commons.math3.linear.RealMatrix exp(org.apache.commons.math3.linear.RealMatrix matrix)

Calculate the "matrix exponential" (expm). Note: The function currently requires jblas. If jblas is not availabe on your system, an exception will be thrown. A future version of this function may implement a fall back.

Parameters:

matrix - The given matrix.

Returns:

The exp(matrix).

transpose

public static double[][] transpose(double[][] matrix)

Transpose a matrix

Parameters:

matrix - The given matrix.

Returns:

The transposed matrix.

pseudoInverse

public static double[][] pseudoInverse(double[][] matrix)

Pseudo-Inverse of a matrix calculated in the least square sense.

Parameters:

matrix - The given matrix A.

Returns:

pseudoInverse The pseudo-inverse matrix P, such that A*P*A = A and P*A*P = P

pseudoInverse

public static double[][] pseudoInverse(LinearAlgebra.SolverBackend solverBackend,
 double[][] matrix)

diag

public static double[][] diag(double[] vector)

Generates a diagonal matrix with the input vector on its diagonal

Parameters:

vector - The given matrix A.

Returns:

diagonalMatrix The matrix with the vectors entries on its diagonal

multMatrices

public static double[][] multMatrices(double[][] left,
 double[][] right)

Multiplication of two matrices.

Parameters:

left - The matrix A.

right - The matrix B

Returns:

product The matrix product of A*B (if suitable)

multMatrixVector

public static double[] multMatrixVector(double[][] matrix,
 double[] vector)

Multiplication of matrix and vector. The vector array is interpreted as column vector.

Parameters:

matrix - The matrix A.

vector - The vector v

Returns:

product The matrix product of A*v (if suitable)

matrixPow

public static double[][] matrixPow(double[][] matrix,
 double exponent)

Matrix power. Tries to calculate a matrix A such that M^{exponent} = A.

Parameters:

matrix - The matrix M of which we like to have the power.

exponent - The exponent.

Returns:

The exponent-th power of M

matrixExp

public static double[][] matrixExp(double[][] matrix)

Matrix exponential. Tries to calculate the matrix A such that exp(M) = A.

Parameters:

matrix - The matrix M

Returns:

exp(M)

matrixLog

public static double[][] matrixLog(double[][] matrix)

Matrix logarithm. Tries to calculate the matrix A such that log(M) = A.

Parameters:

matrix - The matrix M

Returns:

log(M)

matrixNormFrobeniusSquared

public static double matrixNormFrobeniusSquared(double[][] matrix)

Matrix Frobenius norm squared ||M||^2.

Parameters:

matrix - The matrix M

Returns:

The norm squared ||M||^2.

matrixTrace

public static double matrixTrace(double[][] matrix)

Matrix trace tr(M).

Parameters:

matrix - The matrix M

Returns:

The trace tr(M)

matrixIsRowZero

public static boolean matrixIsRowZero(double[][] matrix,
 int i)

matrixIsColZero

public static boolean matrixIsColZero(double[][] matrix,
 int i)

solveTikhonovViaNormalEquations

public static double[] solveTikhonovViaNormalEquations(double[][] matrix,
 double[] rhs,
 double regularizationLambda)

Solves the Tikhonov-regularized normal equations

    (B^T B + lambda I) x = B^T beta.

The normal matrix is assembled explicitly and solved by Cholesky decomposition. Forming the unregularized normal matrix squares the spectral condition number of B. If Cholesky fails, this method therefore solves the original least-squares system for lambda = 0, or its augmented form for lambda > 0, instead of applying an SVD to B^T B.

Parameters:

matrix - The matrix B.

rhs - The right-hand side beta.

regularizationLambda - The finite, non-negative regularization parameter lambda.

Returns:

The Tikhonov-regularized solution x.

solveTikhonovViaNormalEquations

public static double[] solveTikhonovViaNormalEquations(LinearAlgebra.SolverBackend solverBackend,
 double[][] matrix,
 double[] rhs,
 double regularizationLambda)

Solves the Tikhonov-regularized normal equations using an explicit backend. See solveTikhonovViaNormalEquations(double[][], double[], double) for the equation and conditioning characteristics.

Parameters:

solverBackend - The solver backend.

matrix - The matrix B.

rhs - The right-hand side beta.

regularizationLambda - The finite, non-negative regularization parameter lambda.

Returns:

The Tikhonov-regularized solution x.

solveLinearEquationCholesky

public static double[] solveLinearEquationCholesky(double[][] matrix,
 double[] rhs)

solveLinearEquationCholesky

public static double[] solveLinearEquationCholesky(LinearAlgebra.SolverBackend solverBackend,
 double[][] matrix,
 double[] rhs)