 The open source CFD toolbox
EigenMatrix< cmptType > Class Template Reference

EigenMatrix (i.e. eigendecomposition or spectral decomposition) decomposes a diagonalisable nonsymmetric real square matrix into its canonical form, whereby the matrix is represented in terms of its eigenvalues and eigenvectors. More...

## Public Member Functions

EigenMatrix ()=delete
No default construct. More...

EigenMatrix (const EigenMatrix &)=delete
No copy construct. More...

EigenMatrixoperator= (const EigenMatrix &)=delete
No copy assignment. More...

EigenMatrix (const SquareMatrix< cmptType > &A)
Construct from a SquareMatrix<cmptType> More...

EigenMatrix (const SquareMatrix< cmptType > &A, bool symmetric)
Construct from a SquareMatrix<cmptType> and symmetry flag. More...

const DiagonalMatrix< cmptType > & EValsRe () const
Return real eigenvalues or real part of complex eigenvalues. More...

const DiagonalMatrix< cmptType > & EValsIm () const

const SquareMatrix< cmptType > & EVecs () const

const SquareMatrix< complexcomplexEVecs () const
Return right eigenvectors in unpacked form. More...

## Detailed Description

template<class cmptType>
class Foam::EigenMatrix< cmptType >

EigenMatrix (i.e. eigendecomposition or spectral decomposition) decomposes a diagonalisable nonsymmetric real square matrix into its canonical form, whereby the matrix is represented in terms of its eigenvalues and eigenvectors.

The eigenvalue equation (i.e. eigenvalue problem) is:

$A v = \lambda v$

where

 $$A$$ = a diagonalisable square matrix of dimension m-by-m $$v$$ = a (non-zero) vector of dimension m (right eigenvector) $$\lambda$$ = a scalar corresponding to v (eigenvalue)

If A is symmetric, the following relation is satisfied:

$A = v*D*v^T$

where

 $$D$$ = diagonal real eigenvalue matrix $$v$$ = orthogonal eigenvector matrix

If A is not symmetric, D becomes a block diagonal matrix wherein the real eigenvalues are present on the diagonal within 1-by-1 blocks, and complex eigenvalues within 2-by-2 blocks, i.e. $$\lambda + i \mu$$ with $$[\lambda, \mu; -\mu, \lambda]$$.

The columns of v represent eigenvectors corresponding to eigenvalues, satisfying the eigenvalue equation. Even though eigenvalues of a matrix are unique, eigenvectors of the matrix are not. For the same eigenvalue, the corresponding eigenvector can be real or complex with non-unique entries. In addition, the validity of the equation $$A = v*D*v^T$$ depends on the condition number of v, which can be ill-conditioned, or singular for invalidated equations.

References:

        OpenFOAM-compatible implementation:
Passalacqua, A., Heylmun, J., Icardi, M.,
Madadi, E., Bachant, P., & Hu, X. (2019).
OpenQBMM 5.0.1 for OpenFOAM 7, Zenodo.
DOI:10.5281/zenodo.3471804

Implementations for the functions:
'tridiagonaliseSymmMatrix', 'symmTridiagonalQL',
'Hessenberg' and 'realSchur' (based on ALGOL-procedure:tred2):
Wilkinson, J. H., & Reinsch, C. (1971).
In Bauer, F. L. & Householder A. S. (Eds.),
Handbook for Automatic Computation: Volume II: Linear Algebra.
(Vol. 186), Springer-Verlag Berlin Heidelberg.
DOI: 10.1007/978-3-642-86940-2

Explanations on how real eigenvectors
can be unpacked into complex domain:
Moler, C. (1998).
Re: Eigenvectors.

TNT/JAMA implementation:
Pozo, R. (1997).
Template Numerical Toolkit for linear algebra:
High performance programming with C++
and the Standard Template Library.
The International Journal of Supercomputer Applications
and High Performance Computing, 11(3), 251-263.
DOI:10.1177/109434209701100307

(No particular order) Hicklin, J., Moler, C., Webb, P.,
Boisvert, R. F., Miller, B., Pozo, R., & Remington, K. (2012).
JAMA: A Java Matrix Package 1.0.3.
Retrived from https://math.nist.gov/javanumerics/jama/
Note
• This implementation is an integration of the OpenQBMM eigenSolver class (2019) without any changes to its internal mechanisms. Therefore, no differences between EigenMatrix and eigenSolver (2019) classes should be expected in terms of input-process-output operations.
• The OpenQBMM eigenSolver class derives almost completely from the TNT/JAMA implementation, a public-domain library developed by NIST and MathWorks from 1998 to 2012, available at http://math.nist.gov/tnt/index.html (Retrieved June 6, 2020). Their implementation was based upon EISPACK.
• The tridiagonaliseSymmMatrix, symmTridiagonalQL, Hessenberg and realSchur methods are based on the Algol procedures tred2 by Bowdler, Martin, Reinsch, and Wilkinson, Handbook for Auto. Comp., Vol. II-Linear Algebra, and the corresponding FORTRAN subroutine in EISPACK.
Test-EigenMatrix.C
Source files

Definition at line 178 of file EigenMatrix.H.

## ◆ EigenMatrix() [1/4]

 EigenMatrix ( )
delete

No default construct.

## ◆ EigenMatrix() [2/4]

 EigenMatrix ( const EigenMatrix< cmptType > & )
delete

No copy construct.

## ◆ EigenMatrix() [3/4]

 EigenMatrix ( const SquareMatrix< cmptType > & A )
explicit

Construct from a SquareMatrix<cmptType>

Definition at line 1007 of file EigenMatrix.C.

References A, Foam::abort(), Foam::FatalError, and FatalErrorInFunction.

Here is the call graph for this function:

## ◆ EigenMatrix() [4/4]

 EigenMatrix ( const SquareMatrix< cmptType > & A, bool symmetric )

Construct from a SquareMatrix<cmptType> and symmetry flag.

Does not perform symmetric check

Definition at line 1038 of file EigenMatrix.C.

References A, Foam::abort(), Foam::FatalError, and FatalErrorInFunction.

Here is the call graph for this function:

## ◆ operator=()

 EigenMatrix & operator= ( const EigenMatrix< cmptType > & )
delete

No copy assignment.

## ◆ EValsRe()

 const DiagonalMatrix< cmptType > & EValsRe ( ) const
inline

Return real eigenvalues or real part of complex eigenvalues.

Definition at line 248 of file EigenMatrix.H.

## ◆ EValsIm()

 const DiagonalMatrix< cmptType > & EValsIm ( ) const
inline

Return zero-matrix for real eigenvalues or imaginary part of complex eigenvalues

Definition at line 255 of file EigenMatrix.H.

## ◆ EVecs()

 const SquareMatrix< cmptType > & EVecs ( ) const
inline

Return right eigenvectors matrix where each column is a right eigenvector that corresponds to an eigenvalue

Definition at line 262 of file EigenMatrix.H.

## ◆ complexEVecs()

 const Foam::SquareMatrix< Foam::complex > complexEVecs

Return right eigenvectors in unpacked form.

Definition at line 1076 of file EigenMatrix.C.

References Matrix< Form, Type >::begin(), Matrix< Form, Type >::m(), Foam::mag(), and x.

Here is the call graph for this function:

The documentation for this class was generated from the following files: