TPZEigenSolver

The TPZEigenSolver represents a solver for Eigenvalue problems (EVP) in which the matrix has entries with the type TVar, where TVar = STATE, for real problems, and TVar = CSTATE, for complex problems. It should be used with the TPZEigenAnalysis class. See TPZLapackEigenSolver and TPZKrylovEigenSolver for details on the available solvers in NeoPZ.

Sorting eigenpairs

The returned eigenvalues can be sorted in the following ways:

enum TPZEigenSort

Sorting method for calculated eigenvalues.

Values:

enumerator AbsAscending

Ascending magnitude

enumerator AbsDescending

Descending magnitude

enumerator RealAscending

Ascending real part

enumerator RealDescending

Descending real part

enumerator ImagAscending

Ascending imaginary part

enumerator ImagDescending

Descending imaginary part

enumerator TargetRealPart

Real part closest to target

enumerator TargetImagPart

Imaginary part closest to target

enumerator TargetMagnitude

Magnitude closest to target

Further documentation on TPZEigenSolver

template<typename TVar>
class TPZEigenSolver : public TPZSolver

Defines an interface for eigenvalue problems solvers.

Subclassed by TPZKrylovEigenSolver< TVar >, TPZLapackEigenSolver< TVar >

Eigen

inline int Solve(TPZVec<CTVar> &w, TPZFMatrix<CTVar> &eigenVectors)

Solves the EVP (according to IsGeneralised()) and calculates the eigenvectors.

Parameters

w – [out] Stores the eigenvalues

Returns

Returns 1 if executed correctly

inline int Solve(TPZVec<CTVar> &w)

Solves the EVP (according to IsGeneralised()) and does not calculate the eigenvectors.

Parameters

w – [out] Stores the eigenvalues

Returns

Returns 1 if executed correctly

virtual int SolveEigenProblem(TPZVec<CTVar> &w, TPZFMatrix<CTVar> &eigenVectors) = 0

Solves the Ax=w*x eigenvalue problem and calculates the eigenvectors.

Parameters

  • w – [out] Stores the eigenvalues

  • eigenVectors – [out] Stores the correspondent eigenvectors

Returns

Returns 1 if executed correctly

virtual int SolveEigenProblem(TPZVec<CTVar> &w) = 0

Solves the Ax=w*x eigenvalue problem and does not calculate the eigenvectors.

Parameters

w – [out] Stores the eigenvalues

Returns

Returns 1 if executed correctly

virtual int SolveGeneralisedEigenProblem(TPZVec<CTVar> &w, TPZFMatrix<CTVar> &eigenVectors) = 0

Solves the generalised Ax=w*B*x eigenvalue problem and calculates the eigenvectors.

Parameters

  • w – [out] Stores the eigenvalues

  • eigenVectors – [out] Stores the correspondent eigenvectors

Returns

Returns 1 if executed correctly

virtual int SolveGeneralisedEigenProblem(TPZVec<CTVar> &w) = 0

Solves the generalised Ax=w*B*x eigenvalue problem and does not calculates the eigenvectors.

Parameters

w – [out] Stores the eigenvalues

Returns

Returns 1 if executed correctly

virtual void SetNEigenpairs(int n) = 0

Sets number of Eigenpairs to compute.

Note

In some solvers, n<1 is equal to all.

inline int NEigenpairs() const

Gets number of Eigenpairs to calculate.

inline virtual void SetTarget(TVar t)

Sets target eigenvalue.

Note

If there is a shift of origin or shift and invert spectral transformation associated with the solver, then setting a target will also set the corresponding shift

inline TPZAutoPointer<TPZMatrix<TVar>> MatrixA()

Gets the Matrix A.

inline TPZAutoPointer<TPZMatrix<TVar>> MatrixB()

Gets the Matrix B(for generalised eigenvalue problems)

inline void SetMatrixA(TPZAutoPointer<TPZMatrix<TVar>> mat)

Sets the Matrix A.

inline void SetMatrixB(TPZAutoPointer<TPZMatrix<TVar>> mat)

Sets the Matrix B (for generalised eigenvalue problems)

inline bool IsGeneralised() const

Whether the solver is set for a generalised eigenvalue problem.

virtual void SetAsGeneralised(bool isGeneralised)

Configure the solver to solve a generalised eigenvalue problem.

inline void SetEigenSorting(TPZEigenSort ord)

Decides criterium for sorting the obtained eigenvalues.

Note

By default it is set to TPZEigenSort::EAbsAscending .

inline TPZEigenSort EigenSorting() const

Returns criterium for sorting the obtained eigenvalues.

TPZLapackEigenSolver

This class acts as a wrapper over LAPACK calls that can be used for solving eigenvalue problems. It supports TPZFMatrix and TPZSBMatrix, therefore it can only be used with the structural matrices TPZFStructMatrix and TPZSBandStructMatrix. It provides no additional public interfaces.

Note

This class is also used internally by the TPZFMatrix and TPZSBMatrix classes, thus the specific (and protected) interfaces.

template<typename TVar>
class TPZLapackEigenSolver : public TPZEigenSolver<TVar>

Defines an interface for using LAPACK to solve eigenvalue problems.

Note

This class is only compatible with TPZFMatrix and TPZSBMatrix classes.

TPZKrylovEigenSolver

This class implements a set of Krylov-based eigensolvers for solving standard and generalised EVP problems with no restraints regarding the storage format of the matrix. This class of eigensolvers do not solve for all eigenvalues, but for a small set of the original eigenvalues.

Note

For an excellent and detailed discussion on this class of eigensolvers, one can refer to the Chapters 2 and 3 of SLEPc User Manual and their numerous technical reports.

The Krylov-based eigensolvers search for a set of eigenvalues from a given matrix \(A\) on the Krylov subspace:

\[\text{span}\left\{ v, Av, A^2v, \ldots, A^{n-1}v\right\}.\]

Currently TPZKrylovEigenSolver implements an Arnoldi solver, which is a good solver for computing external eigenvalues.

In this class of solvers, an orthonormal basis for the Krylov subspace is obtained by means of an Arnoldi iteration:

\begin{align*} &\text{Take an input vector $v$ and set $v_0=v$}\\ &\text{for }k=0,1,\ldots,m\\ &\qquad w_k = A v_k\\ &\qquad \text{for }j =0,\ldots,k\\ &\qquad \qquad H(j,k) = w_k.v_k\\ &\qquad \qquad w_k -= H(j,k) v_k\\ &\qquad \text{if } k < m-1\\ &\qquad \qquad H(k+1,k) = \lVert w_k \rVert\\ &\qquad \qquad v_{k+1} = w_k / H(k+1,k) \end{align*}

It is interesting to note that in this iteration, only the product \(A v_k\) has to be performed, thus the sparsity of the matrix is left unchanged.

Note

The matrix \(A\) does not necessarily correspond to the matrix of a standard EVP. See TPZSpectralTransform for details on the matrix that is passed to the Arnoldi iteration.

After the Arnoldi iteration is performed, an EVP for \(H\) is then solved using LAPACK. Given that the dimensions of the Krylov subspace is \(m\ll n_{eq}\), where \(n_{eq}\) is the original number of equations, using a dense matrix for \(H\) does not represent a big impact.

Further documentation on TPZKrylovEigenSolver

template<class TVar>
class TPZKrylovEigenSolver : public TPZEigenSolver<TVar>

Solvers for eigenvalue problems using Krylov methods.

The eigenvalue problem is solved in the projected Krylov subspace obtained by an Arnoldi iteration. See TPZSpectralTransform for possible spectral transformations

BasicUsage

virtual int SolveEigenProblem(TPZVec<CTVar> &w, TPZFMatrix<CTVar> &eigenVectors) override

Solves the Ax=w*x eigenvalue problem and does not calculate the eigenvectors.

Parameters

  • w – [out] Eigenvalues in ascending magnitude order

  • eigenVectors – [out] Stores the correspondent eigenvectors

Returns

Returns 1 if executed correctly

virtual int SolveEigenProblem(TPZVec<CTVar> &w) override

Solves the Ax=w*x eigenvalue problem and does not calculate the eigenvectors.

Parameters

w – [out] Eigenvalues in ascending magnitude order

Returns

Returns 1 if executed correctly

virtual int SolveGeneralisedEigenProblem(TPZVec<CTVar> &w, TPZFMatrix<CTVar> &eigenVectors) override

Solves the generalised Ax=w*B*x eigenvalue problem and calculates the eigenvectors.

Parameters

  • w – [out] Eigenvalues in ascending magnitude order

  • eigenVectors – [out] Stores the correspondent eigenvectors

Returns

Returns 1 if executed correctly

virtual int SolveGeneralisedEigenProblem(TPZVec<CTVar> &w) override

Solves the generalised Ax=w*B*x eigenvalue problem and does not calculates the eigenvectors.

Parameters

w – [out] Eigenvalues in ascending magnitude order

Returns

Returns 1 if executed correctly

void SetSpectralTransform(TPZSpectralTransform<TVar> &s)

Sets spectral transformation to be used (it creates an internal copy)

inline TPZAutoPointer<TPZSpectralTransform<TVar>> SpectralTransform()

Gets spectral transformation to be used.

inline virtual void SetNEigenpairs(int n) override

Sets number of Eigenpairs to calculate.

Note

If the dimension of the Krylov subspace is insufficient, it will be adjusted to n.

inline void SetKrylovDim(int d)

Sets the dimension of the Krylov subspace.

Note

If not set, defaults to 10*nev, where nev is the number of sought eigenvalues.

inline int KrylovDim() const

Gets the dimension of the Krylov subspace.

inline void SetTolerance(RTVar s)

Sets tolerance for norm of the Krylov vectors.

inline RTVar Tolerance() const

Gets tolerances.

virtual void SetTarget(TVar target) override

Set target eigenvalue and adjust spectral transform if needed.

inline void SetKrylovInitialVector(TPZFMatrix<TVar> q)

Sets the first vector to be used in the Krylov subspace.

Note

The input vector will be normalized. If not set, a random vector will be generated.

inline TPZFMatrix<TVar> KrylovInitialVector() const

Gets the first vector used in the Krylov subspace.

bool ArnoldiIteration(const TPZMatrix<TVar> &A, TPZVec<TPZAutoPointer<TPZFMatrix<TVar>>> &Q, TPZFMatrix<TVar> &H)

Performs the Arnoldi iteration on a given matrix.

This iteration creates an orthonormal basis of the Krylov subspace of A. The first vector of the Krylov basis can be set through SetKrylovInitialVector method. The dimension of the Krylov subspace can be set throught SetKrylovDim

Parameters

  • A – [in] Matrix in which the algorithm is performed

  • Q – [out] Arnoldi vectors of A

  • H – [out] Representation of A in basis Q

Returns

returns true if succeeded, false otherwise

TPZSpectralTransform

Spectral transformations are used to create a transformed EVP in which the exterior eigenvalues correspond to the sought eigenvalues of the original problem, and the eigenvectors are left unchanged.

The following table summarises the transformed problem for both standard and generalised EVPs:

Transformation

Standard

Generalised

None

\(A\)

\(B^{-1}A\)

TPZSTShiftOrigin

\(A-\sigma I\)

\(B^{-1}A -\sigma I\)

TPZSTShiftAndInvert

\((A-\sigma I)^{-1}\)

\((A-\sigma B)^{-1}B\)
template<class TVar>
class TPZSpectralTransform : public virtual TPZSavable

Deifnes the interface for the spectral transformations used in the TPZKrylovEigenSolver class.

These are based on transforming the spectrum of the original problem as to accelerate convergence. They are specially important when computing internal eigenvalues.

Subclassed by TPZSTShiftOrigin< TVar >

BasicUsage

TPZSpectralTransform() = default

Default constructor.

virtual TPZSpectralTransform<TVar> *Clone() const = 0

Creates a clone of the spectral transformation.

Protected

virtual TPZAutoPointer<TPZMatrix<TVar>> CalcMatrix(TPZAutoPointer<TPZMatrix<TVar>> A, TPZAutoPointer<TPZMatrix<TVar>> B) const = 0

Calculates the appropriate transformation for a generalised EVP.

virtual TPZAutoPointer<TPZMatrix<TVar>> CalcMatrix(TPZAutoPointer<TPZMatrix<TVar>> A) const = 0

Calculates the appropriate transformation for an EVP.

virtual void TransformEigenvalues(TPZVec<CTVar> &w) const = 0

Calculates the original eigenvalues from the mapped ones.

TPZSTShiftOrigin

template<class TVar>
class TPZSTShiftOrigin : public TPZSpectralTransform<TVar>

Defines the shift of origin spectral transformation.

Subclassed by TPZSTShiftAndInvert< TVar >

BasicUsage

TPZSTShiftOrigin() = default

Default constructor.

inline TPZSTShiftOrigin(const TVar s)

Creates a shift of origin spectral transformation with a given shift.

inline virtual TPZSTShiftOrigin<TVar> *Clone() const override

Creates a clone of the spectral transformation.

inline void SetShift(TVar s)

Sets shift.

inline TVar Shift() const

Gets shift.

Protected

virtual TPZAutoPointer<TPZMatrix<TVar>> CalcMatrix(TPZAutoPointer<TPZMatrix<TVar>> A, TPZAutoPointer<TPZMatrix<TVar>> B) const override

Calculates the appropriate transformation for a generalised EVP.

virtual TPZAutoPointer<TPZMatrix<TVar>> CalcMatrix(TPZAutoPointer<TPZMatrix<TVar>> A) const override

Calculates the appropriate transformation for an EVP.

virtual void TransformEigenvalues(TPZVec<CTVar> &w) const override

Calculates the original eigenvalues from the mapped ones.

TPZSTShiftAndInvert

template<class TVar>
class TPZSTShiftAndInvert : public TPZSTShiftOrigin<TVar>

Defines the shift and invert spectral transformation.

BasicUsage

inline virtual TPZSTShiftAndInvert<TVar> *Clone() const override

Creates a clone of the spectral transformation.

virtual TPZAutoPointer<TPZMatrix<TVar>> CalcMatrix(TPZAutoPointer<TPZMatrix<TVar>> A, TPZAutoPointer<TPZMatrix<TVar>> B) const override

Calculates the appropriate transformation for a generalised EVP.

virtual TPZAutoPointer<TPZMatrix<TVar>> CalcMatrix(TPZAutoPointer<TPZMatrix<TVar>> A) const override

Calculates the appropriate transformation for an EVP.

virtual void TransformEigenvalues(TPZVec<CTVar> &w) const override

Calculates the original eigenvalues from the mapped ones.