org.apache.commons.math.linear
Class EigenDecompositionImpl

java.lang.Object
  extended by org.apache.commons.math.linear.EigenDecompositionImpl
All Implemented Interfaces:
EigenDecomposition

public class EigenDecompositionImpl
extends Object
implements EigenDecomposition

Calculates the eigen decomposition of a symmetric matrix.

The eigen decomposition of matrix A is a set of two matrices: V and D such that A = V D VT. A, V and D are all m × m matrices.

As of 2.0, this class supports only symmetric matrices, and hence computes only real realEigenvalues. This implies the D matrix returned by getD() is always diagonal and the imaginary values returned getImagEigenvalue(int) and getImagEigenvalues() are always null.

When called with a RealMatrix argument, this implementation only uses the upper part of the matrix, the part below the diagonal is not accessed at all.

Eigenvalues are computed as soon as the matrix is decomposed, but eigenvectors are computed only when required, i.e. only when one of the getEigenvector(int), getV(), getVT(), getSolver() methods is called.

This implementation is based on Inderjit Singh Dhillon thesis A New O(n2) Algorithm for the Symmetric Tridiagonal Eigenvalue/Eigenvector Problem, on Beresford N. Parlett and Osni A. Marques paper An Implementation of the dqds Algorithm (Positive Case) and on the corresponding LAPACK routines (DLARRE, DLASQ2, DLAZQ3, DLAZQ4, DLASQ5 and DLASQ6).

Since:
2.0
Version:
$Revision: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $
Author:
Beresford Parlett, University of California, Berkeley, USA (fortran version), Jim Demmel, University of California, Berkeley, USA (fortran version), Inderjit Dhillon, University of Texas, Austin, USA(fortran version), Osni Marques, LBNL/NERSC, USA (fortran version), Christof Voemel, University of California, Berkeley, USA(fortran version)

Constructor Summary
EigenDecompositionImpl(double[] main, double[] secondary, double splitTolerance)
          Calculates the eigen decomposition of the given tridiagonal symmetric matrix.
EigenDecompositionImpl(RealMatrix matrix, double splitTolerance)
          Calculates the eigen decomposition of the given symmetric matrix.
 
Method Summary
 RealMatrix getD()
          Returns the block diagonal matrix D of the decomposition.
 double getDeterminant()
          Return the determinant of the matrix
 RealVector getEigenvector(int i)
          Returns a copy of the ith eigenvector of the original matrix.
 double getImagEigenvalue(int i)
          Returns the imaginary part of the ith eigenvalue of the original matrix.
 double[] getImagEigenvalues()
          Returns a copy of the imaginary parts of the eigenvalues of the original matrix.
 double getRealEigenvalue(int i)
          Returns the real part of the ith eigenvalue of the original matrix.
 double[] getRealEigenvalues()
          Returns a copy of the real parts of the eigenvalues of the original matrix.
 DecompositionSolver getSolver()
          Get a solver for finding the A × X = B solution in exact linear sense.
 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
 

Constructor Detail

EigenDecompositionImpl

public EigenDecompositionImpl(RealMatrix matrix,
                              double splitTolerance)
                       throws InvalidMatrixException
Calculates the eigen decomposition of the given symmetric matrix.

Parameters:
matrix - The symmetric matrix to decompose.
splitTolerance - tolerance on the off-diagonal elements relative to the geometric mean to split the tridiagonal matrix (a suggested value is MathUtils.SAFE_MIN)
Throws:
InvalidMatrixException - (wrapping a ConvergenceException if algorithm fails to converge

EigenDecompositionImpl

public EigenDecompositionImpl(double[] main,
                              double[] secondary,
                              double splitTolerance)
                       throws InvalidMatrixException
Calculates the eigen decomposition of the given tridiagonal symmetric matrix.

Parameters:
main - the main diagonal of the matrix (will be copied)
secondary - the secondary diagonal of the matrix (will be copied)
splitTolerance - tolerance on the off-diagonal elements relative to the geometric mean to split the tridiagonal matrix (a suggested value is MathUtils.SAFE_MIN)
Throws:
InvalidMatrixException - (wrapping a ConvergenceException if algorithm fails to converge
Method Detail

getV

public RealMatrix getV()
                throws InvalidMatrixException
Returns the matrix V of the decomposition.

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

The columns of V are the eigenvectors of the original matrix.

Specified by:
getV in interface EigenDecomposition
Returns:
the V matrix
Throws:
InvalidMatrixException

getD

public RealMatrix getD()
                throws InvalidMatrixException
Returns the block diagonal matrix D of the decomposition.

D is a block diagonal matrix.

Real eigenvalues are on the diagonal while complex values are on 2x2 blocks { {real +imaginary}, {-imaginary, real} }.

Specified by:
getD in interface EigenDecomposition
Returns:
the D matrix
Throws:
InvalidMatrixException
See Also:
EigenDecomposition.getRealEigenvalues(), EigenDecomposition.getImagEigenvalues()

getVT

public RealMatrix getVT()
                 throws InvalidMatrixException
Returns the transpose of the matrix V of the decomposition.

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

The columns of V are the eigenvectors of the original matrix.

Specified by:
getVT in interface EigenDecomposition
Returns:
the transpose of the V matrix
Throws:
InvalidMatrixException

getRealEigenvalues

public double[] getRealEigenvalues()
                            throws InvalidMatrixException
Returns a copy of the real parts of the eigenvalues of the original matrix.

Specified by:
getRealEigenvalues in interface EigenDecomposition
Returns:
a copy of the real parts of the eigenvalues of the original matrix
Throws:
InvalidMatrixException
See Also:
EigenDecomposition.getD(), EigenDecomposition.getRealEigenvalue(int), EigenDecomposition.getImagEigenvalues()

getRealEigenvalue

public double getRealEigenvalue(int i)
                         throws InvalidMatrixException,
                                ArrayIndexOutOfBoundsException
Returns the real part of the ith eigenvalue of the original matrix.

Specified by:
getRealEigenvalue in interface EigenDecomposition
Parameters:
i - index of the eigenvalue (counting from 0)
Returns:
real part of the ith eigenvalue of the original matrix
Throws:
InvalidMatrixException
ArrayIndexOutOfBoundsException
See Also:
EigenDecomposition.getD(), EigenDecomposition.getRealEigenvalues(), EigenDecomposition.getImagEigenvalue(int)

getImagEigenvalues

public double[] getImagEigenvalues()
                            throws InvalidMatrixException
Returns a copy of the imaginary parts of the eigenvalues of the original matrix.

Specified by:
getImagEigenvalues in interface EigenDecomposition
Returns:
a copy of the imaginary parts of the eigenvalues of the original matrix
Throws:
InvalidMatrixException
See Also:
EigenDecomposition.getD(), EigenDecomposition.getImagEigenvalue(int), EigenDecomposition.getRealEigenvalues()

getImagEigenvalue

public double getImagEigenvalue(int i)
                         throws InvalidMatrixException,
                                ArrayIndexOutOfBoundsException
Returns the imaginary part of the ith eigenvalue of the original matrix.

Specified by:
getImagEigenvalue in interface EigenDecomposition
Parameters:
i - index of the eigenvalue (counting from 0)
Returns:
imaginary part of the ith eigenvalue of the original matrix
Throws:
InvalidMatrixException
ArrayIndexOutOfBoundsException
See Also:
EigenDecomposition.getD(), EigenDecomposition.getImagEigenvalues(), EigenDecomposition.getRealEigenvalue(int)

getEigenvector

public RealVector getEigenvector(int i)
                          throws InvalidMatrixException,
                                 ArrayIndexOutOfBoundsException
Returns a copy of the ith eigenvector of the original matrix.

Specified by:
getEigenvector in interface EigenDecomposition
Parameters:
i - index of the eigenvector (counting from 0)
Returns:
copy of the ith eigenvector of the original matrix
Throws:
InvalidMatrixException
ArrayIndexOutOfBoundsException
See Also:
EigenDecomposition.getD()

getDeterminant

public double getDeterminant()
Return the determinant of the matrix

Specified by:
getDeterminant in interface EigenDecomposition
Returns:
determinant of the matrix

getSolver

public DecompositionSolver getSolver()
Get a solver for finding the A × X = B solution in exact linear sense.

Specified by:
getSolver in interface EigenDecomposition
Returns:
a solver


Copyright © 2003-2011 Apache Software Foundation. All Rights Reserved.