Eigensolvers

Functions for computing eigenvalues and eigenvectors at compile time. More...

Classes
class	consteig::EigenSolver< T, S >
	Convenience class that computes both eigenvalues and eigenvectors. More...

Functions
template<typename T , Size S>
constexpr Matrix< T, S, S >	consteig::eig (Matrix< T, S, S > a, const T symmetryTolerance)
	Reduce a matrix to quasi-upper-triangular (Schur) form.
template<typename T , Size S>
constexpr Matrix< Complex< T >, S, 1 >	consteig::eigenvalues (const Matrix< T, S, S > &a)
	Compute the eigenvalues of a real square matrix.
template<typename T , Size R, Size C>
static constexpr bool	consteig::checkEigenValues (const Matrix< T, R, C > &a, const Matrix< Complex< T >, R, 1 > &lambda, const T thresh)
	Verify computed eigenvalues against matrix invariants.
template<typename T , Size S>
constexpr Matrix< Complex< T >, S, S >	consteig::eigenvectors (const Matrix< T, S, S > &A, const Matrix< Complex< T >, S, 1 > &eigenvalues)
	Compute eigenvectors given a matrix and its eigenvalues.

Detailed Description

Functions for computing eigenvalues and eigenvectors at compile time.

Function Documentation

eig()

template<typename T , Size S>

constexpr Matrix< T, S, S > consteig::eig ( Matrix< T, S, S > a, const T symmetryTolerance )

constexpr

Reduce a matrix to quasi-upper-triangular (Schur) form.

Routes to the single-shift or double-shift QR solver based on the symmetry of a (controlled by symmetryTolerance). The returned matrix is in real Schur form: diagonal entries are the real eigenvalues, and 2×2 diagonal blocks encode complex conjugate pairs.

In most cases you want eigenvalues or eigenvectors rather than this function directly.

Template Parameters

T	Floating-point scalar type.
S	Matrix dimension.

Parameters

a	Real square matrix.
symmetryTolerance	Threshold for routing to the symmetric solver. Default: CONSTEIG_DEFAULT_SYMMETRIC_TOLERANCE.

Returns

Quasi-upper-triangular matrix in real Schur form.

Precondition

T must be a floating-point type (enforced by static_assert).

eigenvalues()

template<typename T , Size S>

constexpr Matrix< Complex< T >, S, 1 > consteig::eigenvalues ( const Matrix< T, S, S > & a )

constexpr

Compute the eigenvalues of a real square matrix.

Returns the complete spectrum as a column vector of Complex values. Real eigenvalues have zero imaginary part; complex eigenvalues appear as conjugate pairs.

Internally promotes to double (or long double if CONSTEIG_USE_LONG_DOUBLE is defined) for better numerical stability, then narrows back to T for the result.

Template Parameters

T	Floating-point scalar type of the input matrix.
S	Matrix dimension.

Parameters

a	Real S×S matrix.

Returns

S×1 column vector of eigenvalues as Complex<T>. No particular ordering is guaranteed.

Note

Accuracy on well-conditioned matrices: ~1e-9. Accuracy on defective matrices (Jordan blocks): ~0.03. See the verification documentation for details.

static constexpr consteig::Matrix<double, 2, 2> A{{
    {0.0, -1.0},
    {1.0,  0.0}
}};
static constexpr auto eigs = consteig::eigenvalues(A);
// eigs(0,0) ≈ Complex{0.0,  1.0}
// eigs(1,0) ≈ Complex{0.0, -1.0}

checkEigenValues()

template<typename T , Size R, Size C>

static constexpr bool consteig::checkEigenValues ( const Matrix< T, R, C > & a, const Matrix< Complex< T >, R, 1 > & lambda, const T thresh )

inlinestaticconstexpr

Verify computed eigenvalues against matrix invariants.

Checks two matrix invariants:

1. Trace: sum of eigenvalues must equal the matrix trace within thresh.
2. Determinant (only for R <= 4): product of eigenvalues must equal det(a) within a scaled tolerance.

Use this in static_assert blocks to validate eigenvalue correctness at compile time:

static constexpr auto eigs = consteig::eigenvalues(A);
static_assert(consteig::checkEigenValues(A, eigs, 1e-9), "Bad eigenvalues");

Template Parameters

T	Floating-point scalar type.
R	Number of rows (must equal C).
C	Number of columns.

Parameters

a	Input matrix.
lambda	Eigenvalue column vector from eigenvalues.
thresh	Absolute tolerance for invariant checks.

Returns

true if both invariants hold within thresh.

eigenvectors()

template<typename T , Size S>

constexpr Matrix< Complex< T >, S, S > consteig::eigenvectors ( const Matrix< T, S, S > & A, const Matrix< Complex< T >, S, 1 > & eigenvalues )

constexpr

Compute eigenvectors given a matrix and its eigenvalues.

Uses inverse iteration: for each eigenvalue λ, solves (A - λI)v = b for a normalized vector v. Two iterations are performed per eigenvector, which is typically sufficient given the accuracy of eigenvalues.

Each column of the returned matrix is the eigenvector corresponding to the eigenvalue at the same index in eigenvalues.

Template Parameters

T	Floating-point scalar type.
S	Matrix dimension.

Parameters

A	Real S×S matrix.
eigenvalues	S×1 eigenvalue vector from eigenvalues.

Returns

S×S matrix whose columns are the eigenvectors (as Complex<T>). Column eig_col corresponds to eigenvalues(eig_col,0).

static constexpr auto eigs = consteig::eigenvalues(A);
static constexpr auto vecs = consteig::eigenvectors(A, eigs);
// vecs.col(0) is the eigenvector for eigs(0,0)