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< RealScalar >	ComplexScalar
	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...

GeneralizedEigenSolver &	compute (MatrixType const &A, MatrixType const &B, bool compute_eigenvectors=true)
	Solve the given generalized eigenvalue problem. More...

GeneralizedEigenSolver &	compute_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< Index >	real_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

_MatrixType The 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.

template<typename _MatrixType>

typedef Eigen::Matrix<ComplexScalar, ColsAtCompileTime, 1, Options, MaxColsAtCompileTime, 1> numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::EigenvalueType

Complex vector type used to represent the calculated eigenvalues.

template<typename _MatrixType>

typedef Eigen::Matrix<ComplexScalar, RowsAtCompileTime, ColsAtCompileTime, Options, MaxRowsAtCompileTime, MaxColsAtCompileTime> numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::EigenvectorType

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.

template<typename _MatrixType>

typedef Eigen::Matrix<RealScalar, Eigen::Dynamic, 1, Options, MaxColsAtCompileTime, 1> numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::RealEigenvalueType

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

template<typename _MatrixType>

typedef Eigen::Matrix<RealScalar, RowsAtCompileTime, Eigen::Dynamic, Options, MaxRowsAtCompileTime, MaxColsAtCompileTime> numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::RealEigenvectorType

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.

template<typename _MatrixType>

typedef Eigen::Matrix<RealScalar, RowsAtCompileTime, ColsAtCompileTime, Options & ~Eigen::RowMajor, MaxRowsAtCompileTime, MaxColsAtCompileTime> numeric::linear_algebra::GeneralizedEigenSolver< _MatrixType >::ScratchMatrix

private

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] size The 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]	A	Matrix on the left-hand side of the eigenvalue equation.
[in]	B	Matrix on the right-hand side of the eigenvalue equation.
[in]	compute_eigenvectors	Indicates 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]	A	Matrix on the left-hand side of the eigenvalue equation.
[in]	B	Matrix on the right-hand side of the eigenvalue equation.
[in]	compute_eigenvectors	Indicates 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]	A	Matrix on the left-hand side of the eigenvalue equation.
[in]	B	Matrix on the right-hand side of the eigenvalue equation.
[in]	compute_eigenvectors	Indicates 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

Return the calculated (possibly complex) eigenvalues.

See also: compute()

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

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

Return the number of real solutions that were calculated.

See also: compute()

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

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

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().