EigenDecomposition (Artisynth API documentation)

java.lang.Object
- maspack.matrix.EigenDecomposition

```
public class EigenDecomposition
extends java.lang.Object
```
Forms the eigenvalue decomposition of an n X n matrix M, such that
```
 M V = V D
 
```
where V is an n X n eigenvector matrix and D is an n X n matrix formed from the eigenvalues.
If M is symmetric, then D will be a diagonal matrix formed from the (real-valued) eigenvalues, and V will be orthogonal.
If M is non-symmetric, then the eigenvalues may also include complex conjugate pairs (a + b i), (a - b i), in which case D will be block-diagonal, with each complex conjugate pair forming a block
```
 [  a  b ]
 [ -b  a ]
 
```
If v1 and v2 are the columns of V corresponding to this block, then the eigenvectors corresponding to (a + b i), (a - b i) are (a v1 - b v2 i) and (b v1 + a v2 i). V is no longer guaranteed to be orthogonal, and may also be singular. The methods hqr2 and tlr2 in this class were taken from Jama (http://math.nist.gov/javanumerics/jama).

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DEFAULT_ITERATION_LIMIT` The default iteration limit for computing the SVD.
`static double`	`EPS`
`static int`	`OMIT_V` Specifies that the eigenvector matrix V should not be computed.
`static double`	`one`
`static int`	`SYMMETRIC` Specifies that the symmetric part of M, or 1/2 (M+M^T), is to be factored.
`static double`	`zero`

Constructor Summary

Constructors
Constructor and Description
`EigenDecomposition()` Creates an uninitialized EigenDecomposition.
`EigenDecomposition(Matrix M)` Creates a EigenDecomposition and initializes it for the matrix M.
`EigenDecomposition(Matrix M, int flags)` Creates a EigenDecomposition, sets the computation flags, and initializes it for the matrix M.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`double`	`condition()` Computes the condition number of the original matrix M associated with this decomposition.
`double`	`determinant()` Computes the determinant of the original matrix M associated with this decomposition.
`void`	`factor(Matrix M)` Performs an eigen decomposition on the Matrix M.
`void`	`factor(Matrix M, int flags)` Performs an eigen decomposition on the Matrix M.
`static EigenDecomposition`	`factor(Vector er, Vector ei, DenseMatrix V, Matrix M)` Convenience method that creates an EigenDecomposition, factors it for the matrix M, and stores the resulting eigenvalues and vectors into the corresponding arguments.
`void`	`factorSymmetric(Matrix M)` Performs an eigen decomposition on the symmetric part of the Matrix M.
`void`	`factorSymmetric(Matrix M, int flags)` Performs an eigen decomposition on the symmetric part of the Matrix M.
`static EigenDecomposition`	`factorSymmetric(Vector er, DenseMatrix V, Matrix M)` Convenience method that creates an EigenDecomposition, factors it using a symmetric factorization for the matrix M, and stores the resulting eigenvalues and vectors into the corresponding arguments.
`void`	`get(Vector e, DenseMatrix V)`
`void`	`get(Vector er, Vector ei, DenseMatrix V)` Gets the eigenvalues and eigenvectors associated with the decomposition.
`VectorNd`	`getComplexPairs()`
`void`	`getD(MatrixNd D)` Returns the D matrix associated with this decomposition.
`VectorNd`	`getEigImag()` Returns the imaginary parts of the current eigenvalues associated with this decomposition.
`VectorNd`	`getEigReal()` Returns the real parts of the current eigenvalues associated with this decomposition.
`int`	`getIterationLimit()` Gets the iteration limit for computations.
`double`	`getMaxAbsEig()` Returns the maximum absolute value of all the eigenvalues.
`double`	`getMinAbsEig()` Returns the minimum absolute value of all the eigenvalues.
`MatrixNd`	`getV()` Returns the current eigenvector matrix V associated with this decomposition.
`boolean`	`inverse(MatrixNd MI)` Computes the inverse of the original matrix M associated this decomposition, and places the result in MI.
`static void`	`main(java.lang.String[] args)`
`double`	`norm()` Computes the 2-norm of the original matrix M associated with this decomposition.
`int`	`numEigImag()` Returns the number of imaginary eigenvalues.
`void`	`setIterationLimit(int lim)` Sets the iteration limit for computations.
`boolean`	`solve(MatrixNd X, MatrixNd B)` Solves the linear equation M X = B where M is the original matrix associated with this decomposition, and X and B are matrices.
`boolean`	`solve(VectorNd x, VectorNd b)` Solves the linear equation M x = b where M is the original matrix associated with this decomposition, and x and b are vectors.
`static int`	`tql2(double[] d, double[] e, int n, MatrixNd V, int maxit)` Computes the eigenvalues and eigenvectors of a symmetric tridiagonal matrix This code was taken from Jama (http://math.nist.gov/javanumerics/jama).
`static int`	`tqli(double[] d, double[] e, int n, MatrixNd Z)`
`void`	`tridiag(int n, double[] d, double[] e, double[] buf, MatrixNd Z)`
`void`	`upperhessen(int n, double[] buf, MatrixNd Z)`

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - EPS
```
public static final double EPS
```
    See Also:
    
    Constant Field Values
  - zero
```
public static final double zero
```
    See Also:
    
    Constant Field Values
  - one
```
public static final double one
```
    See Also:
    
    Constant Field Values
  - SYMMETRIC
```
public static final int SYMMETRIC
```
    Specifies that the symmetric part of M, or 1/2 (M+M^T), is to be factored.
    
    See Also:
    
    Constant Field Values
  - OMIT_V
```
public static final int OMIT_V
```
    Specifies that the eigenvector matrix V should not be computed.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_ITERATION_LIMIT
```
public static final int DEFAULT_ITERATION_LIMIT
```
    The default iteration limit for computing the SVD.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - EigenDecomposition
```
public EigenDecomposition(Matrix M)
```
    Creates a EigenDecomposition and initializes it for the matrix M.
    
    Parameters:
    
    M - matrix to perform the SVD on
  - EigenDecomposition
```
public EigenDecomposition(Matrix M,
                          int flags)
```
    Creates a EigenDecomposition, sets the computation flags, and initializes it for the matrix M.
    
    Parameters:
    
    M - matrix to perform the Eigen decomposition on
    
    flags - flags associated with computation
  - EigenDecomposition
```
public EigenDecomposition()
```
    Creates an uninitialized EigenDecomposition.
- Method Detail
  - getIterationLimit
```
public int getIterationLimit()
```
    Gets the iteration limit for computations. The actual number of iterations allowed is this limit value times the minimum dimension of the matrix.
    
    Returns:
    
    iteration limit
    
    See Also:
    
    setIterationLimit(int)
  - setIterationLimit
```
public void setIterationLimit(int lim)
```
    Sets the iteration limit for computations. The actual number of iterations allowed is this limit value times the minimum dimension of the matrix.
    
    Parameters:
    
    lim - iteration limit
    
    See Also:
    
    getIterationLimit()
  - factorSymmetric
```
public void factorSymmetric(Matrix M)
```
    Performs an eigen decomposition on the symmetric part of the Matrix M. The symmetric part is computed as 1/2 (M + M^T).
    
    Parameters:
    
    M - matrix to perform the decomposition on
  - factorSymmetric
```
public void factorSymmetric(Matrix M,
                            int flags)
```
    Performs an eigen decomposition on the symmetric part of the Matrix M. The symmetric part is computed as 1/2 (M + M^T). Computation of V is omitted if OMIT_V is set in flags.
    
    Parameters:
    
    M - matrix to perform the decomposition on
    
    flags - flags to control the decomposition
  - factor
```
public void factor(Matrix M)
```
    Performs an eigen decomposition on the Matrix M. A symmetric decomposition is performed if M is found to be exactly symmetric. However, if M is supposed to be symmetric but is not exactly so because of round-off error, then factorSymmetric(maspack.matrix.Matrix) should be used instead.
    
    Parameters:
    
    M - matrix to perform the decomposition on
  - factor
```
public void factor(Matrix M,
                   int flags)
```
    Performs an eigen decomposition on the Matrix M. Computation of V is omitted if OMIT_V is set in flags. A symmetric decomposition is performed on the symmetric part of M (i.e., 1/2 (M+M^T) if SYMMETRIC is set in flags. A symmetric decomposition will also be permformed if M is found to be exactly symmetric. However, if M is supposed to be symmetric but is not exactly so because of round-off error, then either the SYMMETRIC flag should be specified or factorSymmetric(maspack.matrix.Matrix) should be used instead.
    
    Parameters:
    
    M - matrix to perform the decomposition on
    
    flags - flags to control the decomposition
  - get
```
public void get(Vector e,
                DenseMatrix V)
```
  - get
```
public void get(Vector er,
                Vector ei,
                DenseMatrix V)
```
    Gets the eigenvalues and eigenvectors associated with the decomposition.
    
    Parameters:
    
    er - If not null, returns the real part of the eigenvalues
    
    ei - If not null, returns the imaginary part of the eigenvalues
    
    V - If not null, returns the eigenvectors
    
    Throws:
    
    ImproperStateException - if this decomposition is uninitialized, or if V is non-null but V was not computed
    
    ImproperSizeException - if eig or V are not of the proper dimension and cannot be resized.
  - getV
```
public MatrixNd getV()
```
    Returns the current eigenvector matrix V associated with this decomposition. If V was not computed, returns null. Subsequent factorizations will cause a different V to be created. The returned matrix should not be modified if any subsequent calls are to be made which depend on V (including solve and inverse methods).
    
    Returns:
    
    current V matrix
    
    Throws:
    
    ImproperStateException - if this EigenDecomposition is uninitialized
  - getEigReal
```
public VectorNd getEigReal()
```
    Returns the real parts of the current eigenvalues associated with this decomposition. Subsequent factorizations will cause a different vector to be created. The returned vector should not be modified if any subsequent calls are to be made which depend on it (including solve and inverse methods).
    
    Returns:
    
    real parts of the current eigenvalues
    
    Throws:
    
    ImproperStateException - if this decomposition is uninitialized
  - getEigImag
```
public VectorNd getEigImag()
```
    Returns the imaginary parts of the current eigenvalues associated with this decomposition. Subsequent factorizations will cause a different vector to be created. The returned vector should not be modified if any subsequent calls are to be made which depend on it (including solve and inverse methods).
    
    Returns:
    
    imaginary parts of the current eigenvalues
    
    Throws:
    
    ImproperStateException - if this decomposition is uninitialized
  - getD
```
public void getD(MatrixNd D)
```
    Returns the D matrix associated with this decomposition.
    
    Parameters:
    
    D - matrix to return D in
    
    Throws:
    
    ImproperStateException - if this decomposition is uninitialized
    
    ImproperSizeException - if D is not n X n and cannot be resized
  - numEigImag
```
public int numEigImag()
```
    Returns the number of imaginary eigenvalues. For symmetric matrices, this number is always 0. For unsymmetric matrices, the number is estimated by identifying the the number of complex conjugate pairs whose magnitude exceeds an appropriate number tolerance.
    
    Returns:
    
    number of imaginary eigenvalues
  - getComplexPairs
```
public VectorNd getComplexPairs()
```
  - getMinAbsEig
```
public double getMinAbsEig()
```
    Returns the minimum absolute value of all the eigenvalues.
    
    Returns:
    
    minimum absolute value of all eigenvalues
    
    Throws:
    
    ImproperStateException - if this decomposition is uninitialized
  - getMaxAbsEig
```
public double getMaxAbsEig()
```
    Returns the maximum absolute value of all the eigenvalues.
    
    Returns:
    
    maximum absolute value of all eigenvalues
    
    Throws:
    
    ImproperStateException - if this decomposition is uninitialized
  - factor
```
public static EigenDecomposition factor(Vector er,
                                        Vector ei,
                                        DenseMatrix V,
                                        Matrix M)
```
    Convenience method that creates an EigenDecomposition, factors it for the matrix M, and stores the resulting eigenvalues and vectors into the corresponding arguments. If the argument V is specified as null, then the eigenvector matrix will not be computed.
    
    Parameters:
    
    er - If not null, returns the real part of the eigenvalues
    
    ei - If not null, returns the imaginary part of the eigenvalues
    
    V - If not null, returns the eigenvectors
    
    M - matrix to be factored
    
    Returns:
    
    the resulting EigenDecomposition
  - factorSymmetric
```
public static EigenDecomposition factorSymmetric(Vector er,
                                                 DenseMatrix V,
                                                 Matrix M)
```
    Convenience method that creates an EigenDecomposition, factors it using a symmetric factorization for the matrix M, and stores the resulting eigenvalues and vectors into the corresponding arguments. If the argument V is specified as null, then the eigenvector matrix will not be computed.
    
    Parameters:
    
    er - If not null, returns the (real) eigenvalues
    
    V - If not null, returns the eigenvectors
    
    M - matrix to be factored
    
    Returns:
    
    the resulting EigenDecomposition
  - condition
```
public double condition()
```
    Computes the condition number of the original matrix M associated with this decomposition. This method only works if the decomposition was symmetric.
    
    Returns:
    
    condition number
    
    Throws:
    
    ImproperStateException - if this decomposition is uninitialized or unsymmetric
  - norm
```
public double norm()
```
    Computes the 2-norm of the original matrix M associated with this decomposition. This method only works if the decomposition was symmetric.
    
    Returns:
    
    2-norm
    
    Throws:
    
    ImproperStateException - if this decomposition is uninitialized or unsymmetric
  - determinant
```
public double determinant()
```
    Computes the determinant of the original matrix M associated with this decomposition.
    
    Returns:
    
    determinant
    
    Throws:
    
    ImproperStateException - if this decomposition is uninitialized
  - solve
```
public boolean solve(VectorNd x,
                     VectorNd b)
```
    Solves the linear equation
    M x = b
    where M is the original matrix associated with this decomposition, and x and b are vectors. This method only works if the decomposition was symmetric and if V was computed.
    
    Parameters:
    
    x - unknown vector to solve for
    
    b - constant vector
    
    Returns:
    
    false if M is singular (within working precision)
    
    Throws:
    
    ImproperStateException - if this decomposition is uninitialized or unsymmetric, or if V was not computed.
    
    ImproperSizeException - if b does not have a size compatible with M, or if x does not have a size compatible with M and cannot be resized.
  - solve
```
public boolean solve(MatrixNd X,
                     MatrixNd B)
```
    Solves the linear equation
    M X = B
    where M is the original matrix associated with this decomposition, and X and B are matrices. This method only works if the decomposition was symmetric and if V was computed.
    
    Parameters:
    
    X - unknown matrix to solve for
    
    B - constant matrix
    
    Returns:
    
    false if M is singular (within working precision) and true otherwise.
    
    Throws:
    
    ImproperStateException - if this decomposition is uninitialized or unsymmetric, or if V was not computed.
    
    ImproperSizeException - if B has a different number of rows than M, or if X has a different number of rows than M or a different number of columns than B and cannot be resized.
  - inverse
```
public boolean inverse(MatrixNd MI)
```
    Computes the inverse of the original matrix M associated this decomposition, and places the result in MI. This method only works if the decomposition was symmetric and if V was computed.
    
    Parameters:
    
    MI - matrix in which the inverse is stored
    
    Returns:
    
    false if M is singular (within working precision)
    
    Throws:
    
    ImproperStateException - if this decomposition is uninitialized or unsymmetric, or if V was not computed.
    
    ImproperSizeException - If MI does not have the same size as M and cannot be resized.
  - tridiag
```
public void tridiag(int n,
                    double[] d,
                    double[] e,
                    double[] buf,
                    MatrixNd Z)
```
  - tqli
```
public static int tqli(double[] d,
                       double[] e,
                       int n,
                       MatrixNd Z)
```
  - upperhessen
```
public void upperhessen(int n,
                        double[] buf,
                        MatrixNd Z)
```
  - tql2
```
public static int tql2(double[] d,
                       double[] e,
                       int n,
                       MatrixNd V,
                       int maxit)
```
    Computes the eigenvalues and eigenvectors of a symmetric tridiagonal matrix This code was taken from Jama (http://math.nist.gov/javanumerics/jama). where it was derived from the Algol procedures tql2, by Bowdler, Martin, Reinsch, and Wilkinson, Handbook for Auto. Comp., Vol.ii-Linear Algebra, and the corresponding Fortran subroutine in EISPACK.
    
    Parameters:
    
    d - diagonal elements of the matrix
    
    e - off-diagonal elements of the matrix
    
    n - matrix size
    
    V - if non-null, used to return the eigenvalues.
    
    maxit - iteration limit. If -1, 30*n will be commonly used.
  - main
```
public static void main(java.lang.String[] args)
```

Class EigenDecomposition

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

EPS

zero

one

SYMMETRIC

OMIT_V

DEFAULT_ITERATION_LIMIT

Constructor Detail

EigenDecomposition

EigenDecomposition

EigenDecomposition

Method Detail

getIterationLimit

setIterationLimit

factorSymmetric

factorSymmetric

factor

factor

get

get

getV

getEigReal

getEigImag

getD

numEigImag

getComplexPairs

getMinAbsEig

getMaxAbsEig

factor

factorSymmetric

condition

norm

determinant

solve

solve

inverse

tridiag

tqli

upperhessen

tql2

main