Rosetta  2020.37
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Types | Public Member Functions | Private Types | Private Member Functions | Private Attributes | List of all members
numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType > Class Template Reference

Solves generalized eigenvalue problems. More...

#include <GeneralizedEigenSolver.hh>

Public Types

enum  {
  RowsAtCompileTime = MatrixType::RowsAtCompileTime, ColsAtCompileTime = MatrixType::ColsAtCompileTime, Options = MatrixType::Options, MaxRowsAtCompileTime = MatrixType::MaxRowsAtCompileTime,
  MaxColsAtCompileTime = MatrixType::MaxColsAtCompileTime
}
 
typedef _MatrixType MatrixType
 Alias for the template parameter _MatrixType. More...
 
typedef MatrixType::Index Index
 Alias for the type used to index matrices of MatrixType. More...
 
typedef MatrixType::Scalar Scalar
 Alias for the scalar type used in MatrixType matrices. Note that this must be a real type for this algorithm to work. More...
 
typedef Eigen::NumTraits
< Scalar >::Real 
RealScalar
 Alias for the real component of ScalarType. More...
 
typedef std::complex< RealScalarComplexScalar
 Complex type based on RealScalar. More...
 
typedef Eigen::Matrix
< ComplexScalar,
ColsAtCompileTime, 1, Options,
MaxColsAtCompileTime, 1 > 
EigenvalueType
 Complex vector type used to represent the calculated eigenvalues. More...
 
typedef Eigen::Matrix
< ComplexScalar,
RowsAtCompileTime,
ColsAtCompileTime, Options,
MaxRowsAtCompileTime,
MaxColsAtCompileTime
EigenvectorType
 Complex matrix type used to represent the calculated eigenvectors. More...
 
typedef Eigen::Matrix
< RealScalar, Eigen::Dynamic,
1, Options,
MaxColsAtCompileTime, 1 > 
RealEigenvalueType
 Vector type used to represent the real subset of calculated eigenvalues. More...
 
typedef Eigen::Matrix
< RealScalar,
RowsAtCompileTime,
Eigen::Dynamic, Options,
MaxRowsAtCompileTime,
MaxColsAtCompileTime
RealEigenvectorType
 Matrix type used to represent the real subset of calculated eigenvectors. More...
 

Public Member Functions

 GeneralizedEigenSolver ()
 Default constructor. More...
 
 GeneralizedEigenSolver (Index size)
 Default constructor with memory preallocation. More...
 
 GeneralizedEigenSolver (MatrixType const &A, MatrixType const &B, bool compute_eigenvectors=true)
 Construct and solve the given generalized eigenvalue problem. More...
 
GeneralizedEigenSolvercompute (MatrixType const &A, MatrixType const &B, bool compute_eigenvectors=true)
 Solve the given generalized eigenvalue problem. More...
 
GeneralizedEigenSolvercompute_in_place (MatrixType &A, MatrixType &B, bool compute_eigenvectors=true)
 Solve the given generalized eigenvalue problem in place. More...
 
EigenvalueType eigenvalues () const
 Return the calculated (possibly complex) eigenvalues. More...
 
EigenvectorType eigenvectors () const
 Return the calculated (possibly complex) eigenvectors. More...
 
RealEigenvalueType real_eigenvalues () const
 Return any real eigenvalues that were calculated. More...
 
RealEigenvectorType real_eigenvectors () const
 Return any real eigenvectors that were calculated. More...
 
int num_real_solutions () const
 Return the number of real solutions that were calculated. More...
 
Eigen::ComputationInfo info () const
 Indicate whether or not the eigenvalue problem was successfully solved. More...
 

Private Types

typedef Eigen::Matrix
< RealScalar,
ColsAtCompileTime, 1, Options
&~Eigen::RowMajor,
MaxColsAtCompileTime, 1 > 
ScratchVector
 Vector type meant to be compatible with RGG. Sometimes used to implicitly hold imaginary numbers, even though it is a real number type. More...
 
typedef Eigen::Matrix
< RealScalar,
RowsAtCompileTime,
ColsAtCompileTime, Options
&~Eigen::RowMajor,
MaxRowsAtCompileTime,
MaxColsAtCompileTime
ScratchMatrix
 Matrix type meant to be compatible with RGG. Sometimes used to implicitly hold imaginary numbers, even though it is a real number type. More...
 

Private Member Functions

void extract_eigenvalues (const ScratchVector &eigenvalue_numerators_real, const ScratchVector &eigenvalue_numerators_imaginary, const ScratchVector &eigenvalue_denominators)
 Unpacks the eigenvalues returned by RGG and repacks them into a format that better supports complex numbers. More...
 
void extract_eigenvectors (const ScratchMatrix &eigenvectors)
 Unpacks the eigenvectors returned by RGG and repacks them into a format that better supports complex numbers. More...
 
void extract_real_indices ()
 Determines which eigenvalues are real (i.e. those for which the imaginary component is zero). More...
 

Private Attributes

EigenvalueType eigenvalues_
 Vector containing the calculated eigenvalues. More...
 
EigenvectorType eigenvectors_
 Matrix containing the calculated and normalized eigenvectors. More...
 
std::vector< Indexreal_indices_
 List containing the indices of any real eigenvalues. More...
 
bool eigenvalues_were_computed_
 Flag indicating if compute() has been called yet. More...
 
bool eigenvectors_were_computed_
 Flag indicating if eigenvectors were calculated along with the eigenvalues when compute() was called. More...
 
Eigen::ComputationInfo info_
 Indicates whether or not the calculation was successful. More...
 

Detailed Description

template<typename _MatrixType>
class numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >

Solves generalized eigenvalue problems.

Template Parameters
_MatrixTypeThe types of the two matrices involved in the generalized eigenvalue problem. The template parameter is expected to be an instantiation of the Eigen::Matrix class template. Only real matrices are supported.

The generalized matrix problem is $Ax = \lambda Bx$. Here $A$ and $B$ are real matrices, $x$ is an eigenvector, $\lambda$ is a scalar eigenvalue. The problem is to find pairs of $x$ and $\lambda$ that satisfy the above equation. Note that the standard eigenvalue problem $Ax = \lambda x$ is obtained by setting $B = I$. However, for this problem you should use the dedicated EigenSolver provided by the Eigen library.

Call the compute() method to solve a generalized eigenvalue problem. Alternatively, the $A$ and $B$ matrices can be simply passed to the constructor to solve the problem immediately after construction. Once a solution has been found, call the eigenvalues() and eigenvectors() methods to access the results. Note that even though $A$ and $B$ must be real, the eigenvalues and eigenvectors that solve the problem may be complex. The results returned by this solver are of type std::complex, although the imaginary component may sometimes be null.

This solver is a thin wrapper around the RGG routine provided by EISPACK. The RGG routine itself was converted from Fortran to C++ using fable.

Member Typedef Documentation

template<typename _MatrixType>
typedef std::complex<RealScalar> numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::ComplexScalar

Complex type based on RealScalar.

Complex vector type used to represent the calculated eigenvalues.

Complex matrix type used to represent the calculated eigenvectors.

template<typename _MatrixType>
typedef MatrixType::Index numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::Index

Alias for the type used to index matrices of MatrixType.

template<typename _MatrixType>
typedef _MatrixType numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::MatrixType

Alias for the template parameter _MatrixType.

Vector type used to represent the real subset of calculated eigenvalues.

Matrix type used to represent the real subset of calculated eigenvectors.

template<typename _MatrixType>
typedef Eigen::NumTraits<Scalar>::Real numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::RealScalar

Alias for the real component of ScalarType.

template<typename _MatrixType>
typedef MatrixType::Scalar numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::Scalar

Alias for the scalar type used in MatrixType matrices. Note that this must be a real type for this algorithm to work.

Matrix type meant to be compatible with RGG. Sometimes used to implicitly hold imaginary numbers, even though it is a real number type.

template<typename _MatrixType>
typedef Eigen::Matrix<RealScalar, ColsAtCompileTime, 1, Options & ~Eigen::RowMajor, MaxColsAtCompileTime, 1> numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::ScratchVector
private

Vector type meant to be compatible with RGG. Sometimes used to implicitly hold imaginary numbers, even though it is a real number type.

Member Enumeration Documentation

template<typename _MatrixType>
anonymous enum
Enumerator
RowsAtCompileTime 
ColsAtCompileTime 
Options 
MaxRowsAtCompileTime 
MaxColsAtCompileTime 

Constructor & Destructor Documentation

template<typename _MatrixType>
numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::GeneralizedEigenSolver ( )
inline

Default constructor.

template<typename _MatrixType>
numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::GeneralizedEigenSolver ( Index  size)
inline

Default constructor with memory preallocation.

Parameters
[in]sizeThe amount of space to preallocate for this problem.
See also
GeneralizedEigenSolver()

References numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::real_indices_.

template<typename _MatrixType>
numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::GeneralizedEigenSolver ( MatrixType const &  A,
MatrixType const &  B,
bool  compute_eigenvectors = true 
)
inline

Construct and solve the given generalized eigenvalue problem.

Parameters
[in]AMatrix on the left-hand side of the eigenvalue equation.
[in]BMatrix on the right-hand side of the eigenvalue equation.
[in]compute_eigenvectorsIndicates whether or not the eigenvectors should be calculated. The eigenvalues are always calculated.

This constructor calls compute() to solve the given problem.

See also
GeneralizedEigenSolver()

References numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::compute(), and numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::real_indices_.

Member Function Documentation

template<typename MatrixType >
GeneralizedEigenSolver< MatrixType > & numeric::linear_algebra::GeneralizedEigenSolver< MatrixType >::compute ( MatrixType const &  A,
MatrixType const &  B,
bool  compute_eigenvectors = true 
)

Solve the given generalized eigenvalue problem.

Parameters
[in]AMatrix on the left-hand side of the eigenvalue equation.
[in]BMatrix on the right-hand side of the eigenvalue equation.
[in]compute_eigenvectorsIndicates whether or not the eigenvectors should be calculated. The eigenvalues are always calculated.

This method finds solutions to the problem $Ax = \lambda Bx$. The $A$ and $B$ matrices are not affected by this calculation. Because this behavior is intuitive, it is the default behavior. However, it is also somewhat less efficient. The underlying EISPACK routine uses the $A$ and $B$ matrices for scratch space, so this method has to copy the two matrices to prevent them from being changed. Of course, this copy costs both time and memory. If that time and memory is important to you, use the compute_in_place() method instead.

See also
compute_in_place()
rgg()

Referenced by numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::GeneralizedEigenSolver().

template<typename MatrixType >
GeneralizedEigenSolver< MatrixType > & numeric::linear_algebra::GeneralizedEigenSolver< MatrixType >::compute_in_place ( MatrixType A,
MatrixType B,
bool  compute_eigenvectors = true 
)

Solve the given generalized eigenvalue problem in place.

Parameters
[in]AMatrix on the left-hand side of the eigenvalue equation.
[in]BMatrix on the right-hand side of the eigenvalue equation.
[in]compute_eigenvectorsIndicates whether or not the eigenvectors should be calculated. The eigenvalues are always calculated.

This method finds solutions to the problem $Ax = \lambda Bx$. The computation is performed in place, which save some resources relative to the compute() method. However, the $A$ and $B$ matrices are trashed in the process. Usually the compute() method is a more appropriate choice because the modest improvement in performance is not worth the counterintuitive behavior.

See also
compute()
rgg()

References numeric::linear_algebra::rgg().

template<typename _MatrixType>
EigenvalueType numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::eigenvalues ( ) const
inline
template<typename _MatrixType>
EigenvectorType numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::eigenvectors ( ) const
inline

Return the calculated (possibly complex) eigenvectors.

The returned eigenvectors will be normalized. This method can only be called if the eigenvectors were actually calculated (i.e. compute_eigenvectors = true) in the call to compute(). An assertion will trigger if this is not the case.

See also
compute()

References numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::eigenvectors_, and numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::eigenvectors_were_computed_.

template<typename MatrixType >
void numeric::linear_algebra::GeneralizedEigenSolver< MatrixType >::extract_eigenvalues ( const ScratchVector eigenvalue_numerators_real,
const ScratchVector eigenvalue_numerators_imaginary,
const ScratchVector eigenvalue_denominators 
)
private

Unpacks the eigenvalues returned by RGG and repacks them into a format that better supports complex numbers.

RGG returns information about the eigenvalues in three vectors. The first two vectors are the real and imaginary parts of the numerator, and the third vector is the (real) denominator. The complex eigenvalues can then be calculated as:

\[\lambda = \frac{\mathrm{real\_numerator} + i \times \mathrm{imaginary\_numerator}}{\mathrm{denominator}}\]

See also
compute()
template<typename MatrixType >
void numeric::linear_algebra::GeneralizedEigenSolver< MatrixType >::extract_eigenvectors ( const ScratchMatrix raw_eigenvectors)
private

Unpacks the eigenvectors returned by RGG and repacks them into a format that better supports complex numbers.

The format of the raw_eigenvectors matrix produced by RGG is very dense, because it needs to represent both real and complex eigenvectors. The role of this method is to unpack the information stored in this matrix. The eigenvectors are represented as column vectors, but the exact meaning of each column vector depends on the corresponding eigenvalue. If the j-th eigenvalue is real, then the j-th eigenvector is simply the j-th column of the raw_eigenvectors matrix.

On the other hand, if the j-th eigenvalue is complex then the j-th eigenvector must also be complex. Complex eigenvectors require two columns to fully represent, because they have both real and imaginary components. Fortunately, complex eigenvalues and eigenvectors always come in conjugate pairs: $\alpha + \beta i$ and $\alpha - \beta i$. The columns in raw_eigenvectors explicitly give the first member of that pair, and the second member is implicitly added by the unpacking code.

See also
compute()

References basic::options::OptionKeys::frags::j.

template<typename MatrixType >
void numeric::linear_algebra::GeneralizedEigenSolver< MatrixType >::extract_real_indices ( )
private

Determines which eigenvalues are real (i.e. those for which the imaginary component is zero).

This method fills real_indices_ with the indices of all the real eigenvalues. These indices can also be used to pick out the real eigenvectors, because there is a one-to-one correspondence between the two. The Eigen::internal::isMuchSmallerThan function is used to determine whether or not the imaginary component is negligible relative to the real component.

See also
compute()
real_eigenvalues()
real_eigenvectors()
template<typename _MatrixType>
Eigen::ComputationInfo numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::info ( ) const
inline

Indicate whether or not the eigenvalue problem was successfully solved.

Returns
Eigen::Success if computation was successful, Eigen::NoConvergence otherwise.
See also
compute()

References numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::eigenvalues_were_computed_, and numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::info_.

template<typename _MatrixType>
int numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::num_real_solutions ( ) const
inline
template<typename MatrixType >
GeneralizedEigenSolver< MatrixType >::RealEigenvalueType numeric::linear_algebra::GeneralizedEigenSolver< MatrixType >::real_eigenvalues ( ) const

Return any real eigenvalues that were calculated.

The returned eigenvalues will not be in any sorted order.

See also
compute()
eigenvalues()

Referenced by numeric::kinematic_closure::dixon_eig().

template<typename MatrixType >
GeneralizedEigenSolver< MatrixType >::RealEigenvectorType numeric::linear_algebra::GeneralizedEigenSolver< MatrixType >::real_eigenvectors ( ) const

Return any real eigenvectors that were calculated.

Each real eigenvector corresponds to one real eigenvalue, and the order of eigenvalues returned by real_eigenvalues() will match the order of eigenvectors returned by this method. There is no relation between this method and the order of the complex eigenvalues returned by eigenvalues().

See also
compute()
eigenvectors()

References basic::options::OptionKeys::frags::j.

Referenced by numeric::kinematic_closure::dixon_eig().

Member Data Documentation

template<typename _MatrixType>
EigenvalueType numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::eigenvalues_
private

Vector containing the calculated eigenvalues.

Referenced by numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::eigenvalues().

template<typename _MatrixType>
bool numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::eigenvalues_were_computed_
private
template<typename _MatrixType>
EigenvectorType numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::eigenvectors_
private

Matrix containing the calculated and normalized eigenvectors.

Referenced by numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::eigenvectors().

template<typename _MatrixType>
bool numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::eigenvectors_were_computed_
private

Flag indicating if eigenvectors were calculated along with the eigenvalues when compute() was called.

Referenced by numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::eigenvectors().

template<typename _MatrixType>
Eigen::ComputationInfo numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::info_
private

Indicates whether or not the calculation was successful.

Referenced by numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::info().

template<typename _MatrixType>
std::vector<Index> numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::real_indices_
private

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