Loading...
Searching...
No Matches
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...

#include <EigenMatrix.H>

Public Types

typedef cmptType value_type
 The value type the Matrix contains.

Public Member Functions

 EigenMatrix ()=delete
 No default construct.
 EigenMatrix (const EigenMatrix &)=delete
 No copy construct.
EigenMatrix & operator= (const EigenMatrix &)=delete
 No copy assignment.
 EigenMatrix (const SquareMatrix< cmptType > &A)
 Construct from a SquareMatrix<cmptType>.
 EigenMatrix (const SquareMatrix< cmptType > &A, bool symmetric)
 Construct from a SquareMatrix<cmptType> and symmetry flag.
const DiagonalMatrix< cmptType > & EValsRe () const noexcept
 Return real eigenvalues or real part of complex eigenvalues.
const DiagonalMatrix< cmptType > & EValsIm () const noexcept
 Return zero-matrix for real eigenvalues or imaginary part of complex eigenvalues.
const SquareMatrix< cmptType > & EVecs () const noexcept
 Return right eigenvectors matrix where each column is a right eigenvector that corresponds to an eigenvalue.
const SquareMatrix< complex > complexEVecs () const
 Return right eigenvectors in unpacked form.

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 173 of file EigenMatrix.H.

Member Typedef Documentation

◆ value_type

template<class cmptType>
typedef cmptType value_type

The value type the Matrix contains.

Definition at line 241 of file EigenMatrix.H.

Constructor & Destructor Documentation

◆ EigenMatrix() [1/4]

template<class cmptType>
EigenMatrix ( )
delete

No default construct.

Referenced by EigenMatrix(), EigenMatrix(), and operator=().

Here is the caller graph for this function:

◆ EigenMatrix() [2/4]

template<class cmptType>
EigenMatrix ( const EigenMatrix< cmptType > & )
delete

No copy construct.

References EigenMatrix().

Here is the call graph for this function:

◆ EigenMatrix() [3/4]

template<class cmptType>
EigenMatrix ( const SquareMatrix< cmptType > & A)
explicit

Construct from a SquareMatrix<cmptType>.

Definition at line 1031 of file EigenMatrix.C.

References A, and EigenMatrix().

Here is the call graph for this function:

◆ EigenMatrix() [4/4]

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

Construct from a SquareMatrix<cmptType> and symmetry flag.

Does not perform symmetric check

Definition at line 996 of file EigenMatrix.C.

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

Here is the call graph for this function:

Member Function Documentation

◆ operator=()

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

No copy assignment.

References A, and EigenMatrix().

Here is the call graph for this function:

◆ EValsRe()

template<class cmptType>
const DiagonalMatrix< cmptType > & EValsRe ( ) const
inlinenoexcept

Return real eigenvalues or real part of complex eigenvalues.

Definition at line 282 of file EigenMatrix.H.

References Foam::noexcept.

◆ EValsIm()

template<class cmptType>
const DiagonalMatrix< cmptType > & EValsIm ( ) const
inlinenoexcept

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

Definition at line 291 of file EigenMatrix.H.

References Foam::noexcept.

◆ EVecs()

template<class cmptType>
const SquareMatrix< cmptType > & EVecs ( ) const
inlinenoexcept

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

Definition at line 300 of file EigenMatrix.H.

References Foam::noexcept.

Referenced by complexEVecs().

Here is the caller graph for this function:

◆ complexEVecs()

template<class cmptType>
const Foam::SquareMatrix< Foam::complex > complexEVecs ( ) const

Return right eigenvectors in unpacked form.

Definition at line 1041 of file EigenMatrix.C.

References EVecs(), Foam::mag(), and x.

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