Public Member Functions | List of all members
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
 
 EigenMatrix (const EigenMatrix &)=delete
 
EigenMatrix & operator= (const EigenMatrix &)=delete
 
 EigenMatrix (const SquareMatrix< cmptType > &A)
 
 EigenMatrix (const SquareMatrix< cmptType > &A, bool symmetric)
 
const DiagonalMatrix< cmptType > & EValsRe () const
 
const DiagonalMatrix< cmptType > & EValsIm () const
 
const SquareMatrix< cmptType > & EVecs () const
 
const SquareMatrix< complex > complexEVecs () const
 

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.
            Retrieved from https://bit.ly/3ao4Wat

        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.
See also
Test-EigenMatrix.C
Source files

Definition at line 174 of file EigenMatrix.H.

Constructor & Destructor Documentation

◆ EigenMatrix() [1/4]

EigenMatrix ( )
delete

◆ EigenMatrix() [2/4]

EigenMatrix ( const EigenMatrix< cmptType > &  )
delete

◆ EigenMatrix() [3/4]

EigenMatrix ( const SquareMatrix< cmptType > &  A)
explicit

Definition at line 1000 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 
)

Definition at line 1032 of file EigenMatrix.C.

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

Here is the call graph for this function:

Member Function Documentation

◆ operator=()

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

◆ EValsRe()

const DiagonalMatrix<cmptType>& EValsRe ( ) const
inline

Definition at line 244 of file EigenMatrix.H.

◆ EValsIm()

const DiagonalMatrix<cmptType>& EValsIm ( ) const
inline

Definition at line 251 of file EigenMatrix.H.

◆ EVecs()

const SquareMatrix<cmptType>& EVecs ( ) const
inline

Definition at line 258 of file EigenMatrix.H.

◆ complexEVecs()

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

Definition at line 1069 of file EigenMatrix.C.

References Matrix< SquareMatrix< Type >, Type >::begin(), Foam::roots::complex, Matrix< SquareMatrix< Type >, Type >::m(), Foam::mag(), Foam::transform(), and x.

Here is the call graph for this function:
The documentation for this class was generated from the following files:

Copyright © 2011-2018  OpenFOAM | OPENFOAM® is a registered trademark of OpenCFD Ltd.

Generated by   doxygen 1.8.17