Eigen::TridiagonalEigenSolver< Scalar_ > Class Template Reference

#include <Eigen/src/Eigenvalues/TridiagonalEigenSolver.h>

Detailed Description

template<typename Scalar_>
class Eigen::TridiagonalEigenSolver< Scalar_ >

Computes eigenvalues and eigenvectors of a real symmetric tridiagonal matrix.

This is defined in the Eigenvalues module.

#include <Eigen/Eigenvalues> 

Template Parameters

Scalar_

the (real floating-point) scalar type of the matrix, e.g. float or double.

This solver computes the eigenvalues of a real symmetric tridiagonal matrix \( T \), given by its diagonal and sub-diagonal, using SIMD-accelerated, multi-threaded Sturm-sequence spectral bisection (cf. LAPACK's xSTEBZ), and the corresponding eigenvectors by inverse iteration (cf. LAPACK's xSTEIN). Unlike the implicit-QR path of SelfAdjointEigenSolver::computeFromTridiagonal(), it can compute an arbitrary contiguous subset of the spectrum – by index range or by value range – selected with an EigenvalueRange, and it never pays for eigenvectors that are not requested:

TridiagonalEigenSolver<double> es;
es.compute(diag, subdiag);                            // full spectrum, eigenvalues + eigenvectors
es.compute(diag, subdiag, EigenvaluesOnly);           // full spectrum, eigenvalues only
es.compute(diag, subdiag, ComputeEigenvectors,
           EigenvalueRange::indices(0, 10));          // the 10 smallest eigenpairs
 
// Staged: eigenvalues now, eigenvectors later (only if they turn out to be needed).
es.computeEigenvalues(diag, subdiag, EigenvalueRange::values(vl, vu));
es.computeEigenvectors();
 
// Direct: eigenvectors for already-known eigenvalues.
es.computeEigenvectors(diag, subdiag, eigenvalues);

In every mode the computed eigenvalues are returned by eigenvalues() in non-decreasing order, one entry per selected eigenvalue, and eigenvectors() is the n x m matrix whose column j is a unit-norm eigenvector for eigenvalues()(j).

Besides subset selection, bisection is typically more accurate than the QR algorithm: it resolves each eigenvalue to about one unit in the last place of \( \|T\| \) independently of the others, whereas the QR forward error accumulates through its O(n) sweeps and grows with the matrix size. (Both are backward stable; this is absolute accuracy relative to \( \|T\| \), not high relative accuracy for eigenvalues much smaller than \( \|T\| \).)

The eigenvectors are those of the tridiagonal \( T \) itself; recovering eigenvectors of a dense matrix additionally requires the Householder back-transform performed by SelfAdjointEigenSolver::compute().

Note

The eigenvalues of a complex Hermitian tridiagonal matrix depend only on the moduli of its off-diagonal entries: it is unitarily similar (via a diagonal phase matrix) to the real symmetric tridiagonal with the same diagonal and off-diagonals \( |\beta_k| \). So to compute them, pass subdiag.cwiseAbs() as the real sub-diagonal. The eigenvectors, by contrast, differ from the real ones by that diagonal phase and cannot be recovered this way.

See also

EigenvalueRange, SelfAdjointEigenSolver::computeFromTridiagonal(), class Tridiagonalization

Public Types
using	MatrixType
	Type for the eigenvector matrix: dynamic-size, one column per selected eigenvalue.
using	Scalar
	Scalar type of the matrix; must be real.
using	VectorType
	Type for the eigenvalues and the input diagonals: a dynamic-size column vector.

Public Member Functions
template<typename DiagType, typename SubdiagType>
TridiagonalEigenSolver &	compute (const MatrixBase< DiagType > &diag, const MatrixBase< SubdiagType > &subdiag, int options=ComputeEigenvectors, const EigenvalueRange &range=EigenvalueRange::all())
	Computes the selected eigenvalues, and optionally eigenvectors, of a real symmetric tridiagonal matrix.
template<typename DiagType, typename SubdiagType>
TridiagonalEigenSolver &	computeEigenvalues (const MatrixBase< DiagType > &diag, const MatrixBase< SubdiagType > &subdiag, const EigenvalueRange &range=EigenvalueRange::all())
	Computes the selected eigenvalues (only) of a real symmetric tridiagonal matrix.
TridiagonalEigenSolver &	computeEigenvectors ()
	Computes eigenvectors for the eigenvalues of the preceding compute step, by inverse iteration.
template<typename DiagType, typename SubdiagType, typename EivalsType>
TridiagonalEigenSolver &	computeEigenvectors (const MatrixBase< DiagType > &diag, const MatrixBase< SubdiagType > &subdiag, const MatrixBase< EivalsType > &eigenvalues)
	Computes eigenvectors of a tridiagonal matrix by inverse iteration from known eigenvalues.
const VectorType &	eigenvalues () const
	Returns the computed eigenvalues, in non-decreasing order.
const MatrixType &	eigenvectors () const
	Returns the computed eigenvectors, one column per eigenvalue.
ComputationInfo	info () const
	Reports whether the computation was successful.
	TridiagonalEigenSolver ()=default
	Default constructor. Call compute() before querying any result.
template<typename DiagType, typename SubdiagType>
	TridiagonalEigenSolver (const MatrixBase< DiagType > &diag, const MatrixBase< SubdiagType > &subdiag, int options=ComputeEigenvectors, const EigenvalueRange &range=EigenvalueRange::all())
	Constructor; computes the eigendecomposition of the given tridiagonal matrix.
	TridiagonalEigenSolver (Index size)
	Constructor pre-allocating room for the full spectrum of a matrix of dimension size.

Constructor & Destructor Documentation

TridiagonalEigenSolver()

template<typename Scalar_>

template<typename DiagType, typename SubdiagType>

Eigen::TridiagonalEigenSolver< Scalar_ >::TridiagonalEigenSolver ( const MatrixBase< DiagType > & diag, const MatrixBase< SubdiagType > & subdiag, int options = ComputeEigenvectors, const EigenvalueRange & range = EigenvalueRange::all() )

inline

Constructor; computes the eigendecomposition of the given tridiagonal matrix.

Equivalent to default construction followed by compute(diag, subdiag, options, range).

Member Function Documentation

compute()

template<typename Scalar_>

template<typename DiagType, typename SubdiagType>

TridiagonalEigenSolver & Eigen::TridiagonalEigenSolver< Scalar_ >::compute ( const MatrixBase< DiagType > & diag, const MatrixBase< SubdiagType > & subdiag, int options = ComputeEigenvectors, const EigenvalueRange & range = EigenvalueRange::all() )

inline

Computes the selected eigenvalues, and optionally eigenvectors, of a real symmetric tridiagonal matrix.

Parameters

[in]	diag	The diagonal of the matrix \( T \) (length n).
[in]	subdiag	The sub-diagonal of \( T \) (length n-1).
[in]	options	Either ComputeEigenvectors (the default) or EigenvaluesOnly.
[in]	range	Which eigenvalues to compute (see EigenvalueRange); defaults to the whole spectrum.

Returns

Reference to *this

Equivalent to computeEigenvalues(diag, subdiag, range), followed – when options is ComputeEigenvectors and the eigenvalues were computed successfully – by computeEigenvectors().

computeEigenvalues()

template<typename Scalar_>

template<typename DiagType, typename SubdiagType>

TridiagonalEigenSolver & Eigen::TridiagonalEigenSolver< Scalar_ >::computeEigenvalues	(	const MatrixBase< DiagType > &	diag,
		const MatrixBase< SubdiagType > &	subdiag,
		const EigenvalueRange &	range = EigenvalueRange::all() )

Computes the selected eigenvalues (only) of a real symmetric tridiagonal matrix.

Parameters

[in]	diag	The diagonal of the matrix \( T \) (length n).
[in]	subdiag	The sub-diagonal of \( T \) (length n-1).
[in]	range	Which eigenvalues to compute (see EigenvalueRange); defaults to the whole spectrum.

Returns

Reference to *this

After the call, eigenvalues() returns the selected eigenvalues in non-decreasing order (one entry per selected eigenvalue), and info() reports Success, or NoConvergence if the input contains a non-finite entry. The tridiagonal is retained, so the eigenvectors can be obtained afterwards with computeEigenvectors() – and need never be computed if they turn out not to be required.

computeEigenvectors() [1/2]

template<typename Scalar_>

TridiagonalEigenSolver & Eigen::TridiagonalEigenSolver< Scalar_ >::computeEigenvectors ( )

inline

Computes eigenvectors for the eigenvalues of the preceding compute step, by inverse iteration.

Returns

Reference to *this

Completes a staged solve: call it after computeEigenvalues() to compute the eigenvectors for the eigenvalues just found, using the retained tridiagonal. See computeEigenvectors(const MatrixBase<DiagType>&, const MatrixBase<SubdiagType>&, const MatrixBase<EivalsType>&) for the algorithm and its guarantees.

Precondition

A successful computeEigenvalues() (or compute()) call.

computeEigenvectors() [2/2]

template<typename Scalar_>

template<typename DiagType, typename SubdiagType, typename EivalsType>

TridiagonalEigenSolver & Eigen::TridiagonalEigenSolver< Scalar_ >::computeEigenvectors	(	const MatrixBase< DiagType > &	diag,
		const MatrixBase< SubdiagType > &	subdiag,
		const MatrixBase< EivalsType > &	eigenvalues )

Computes eigenvectors of a tridiagonal matrix by inverse iteration from known eigenvalues.

Parameters

[in]	diag	The diagonal of the symmetric tridiagonal matrix \( T \) (length n).
[in]	subdiag	The sub-diagonal of \( T \) (length n-1).
[in]	eigenvalues	The eigenvalues whose eigenvectors are wanted, in non-decreasing order (e.g. the output of computeEigenvalues()). Length m \(\le\) n.

Returns

Reference to *this

Computes an eigenvector of \( T \) for each supplied eigenvalue by inverse iteration (LAPACK's xSTEIN, built on the xLAGTF / xLAGTS factorization and overflow-safe solve of the deliberately near-singular \( T - \lambda I \)), reorthogonalizing within tight clusters so that a degenerate cluster yields an orthonormal basis. After the call, eigenvectors() returns the n x m matrix whose column j is a unit-norm eigenvector for eigenvalues[j], and eigenvalues() returns the supplied eigenvalues. Shifts that are insufficiently accurate at their disconnected block's scale are refined internally before iteration, without changing the eigenvalues returned by eigenvalues().

Subsets. This is the natural companion to the subset-selecting eigenvalue path (see EigenvalueRange): pass that subset as eigenvalues and you get back exactly those m eigenvectors – the result has one column per supplied eigenvalue and costs one inverse-iteration solve each, so you never pay for vectors you did not ask for.

Note

The eigenvalues must be sorted in non-decreasing order, as the cluster reorthogonalization relies on it.

If any eigenvector fails to converge within the internal inverse-iteration step limit, the vectors are still returned but info() reports NoConvergence (cf. LAPACK xSTEIN).

The inverse iteration is bit-identical for any number of threads. The eigenvectors of a numerically degenerate cluster may nonetheless differ in their last bits between a single- and a multi-threaded run, because the cluster refinement uses parallel (non-associative) matrix products; each result is an equally valid orthonormal basis of the same invariant subspace.

Warning

Cluster reorthogonalization is performed only among the supplied eigenvalues. The returned eigenvectors are always mutually orthonormal, but they are not orthogonalized against eigenvectors of a degenerate cluster that lie outside eigenvalues (those are never computed). If a requested subset slices through the middle of a numerically degenerate cluster, supply the whole cluster (widen the range) to obtain the correct invariant subspace. For well-separated eigenvalues, or when the subset covers each cluster entirely, this never matters.

See also

computeEigenvalues(), eigenvectors()

eigenvalues()

template<typename Scalar_>

const VectorType & Eigen::TridiagonalEigenSolver< Scalar_ >::eigenvalues ( ) const

inline

Returns the computed eigenvalues, in non-decreasing order.

Precondition

compute(), computeEigenvalues() or computeEigenvectors() has been called.

The returned vector has one entry per selected eigenvalue, so a subset request yields a vector shorter than the matrix dimension. Eigenvalues are repeated according to their algebraic multiplicity.

eigenvectors()

template<typename Scalar_>

const MatrixType & Eigen::TridiagonalEigenSolver< Scalar_ >::eigenvectors ( ) const

inline

Returns the computed eigenvectors, one column per eigenvalue.

Precondition

The eigenvectors have been computed (compute() with ComputeEigenvectors, or one of the computeEigenvectors() overloads).

Column j of the returned n x m matrix is a unit-norm eigenvector of \( T \) for eigenvalues()(j); the columns are mutually orthonormal.

info()

template<typename Scalar_>

ComputationInfo Eigen::TridiagonalEigenSolver< Scalar_ >::info ( ) const

inline

Reports whether the computation was successful.

Returns

Success if the computation was successful, NoConvergence otherwise.

---

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

• /builds/libeigen/eigen/Eigen/src/Eigenvalues/TridiagonalEigenSolver.h