Linear Algebra Backend

The backend module provides computational routines for eigenvalue analysis and stability classification.

Backend Classes

class hiten.algorithms.linalg.backend._LinalgBackend[source]

Bases: _HitenBaseBackend

Minimal backend for linear algebra operations.

Stateless wrapper exposing the core linear-algebra routines used across the library. Provides a small object interface while preserving the existing module-level API for backward compatibility.

Parameters:

system_type (_SystemType, optional) – The type of system to analyze. Default is CONTINUOUS.

run(**kwargs)[source]

Run the linear algebra backend.

Parameters:

**kwargs – Additional keyword arguments passed to the run method.

Return type:

Any

eigenvalue_decomposition(A, delta=0.0001)[source]

Classify eigenvalue-eigenvector pairs into stable, unstable, and center subspaces.

Performs eigenvalue decomposition and classifies the spectrum based on stability criteria for either continuous-time or discrete-time dynamical systems. Each eigenvector is pivot-normalized for consistent representation.

Parameters:

  • A (numpy.ndarray, shape (n, n)) – Real or complex square matrix to analyze.

  • delta (float, optional) – Half-width of neutral band around stability threshold. Default is 1e-4. For continuous systems: absolute value of real part of lambda < delta -> center For discrete systems: absolute value of (absolute value of lambda - 1) < delta -> center

Returns:

  • sn (numpy.ndarray) – Stable eigenvalues. For continuous: real part of lambda < -delta. For discrete: absolute value of lambda < 1-delta.

  • un (numpy.ndarray) – Unstable eigenvalues. For continuous: real part of lambda > +delta. For discrete: absolute value of lambda > 1+delta.

  • cn (numpy.ndarray) – Center eigenvalues (neutral spectrum within delta band).

  • Ws (numpy.ndarray, shape (n, n_s)) – Stable eigenvectors stacked column-wise.

  • Wu (numpy.ndarray, shape (n, n_u)) – Unstable eigenvectors stacked column-wise.

  • Wc (numpy.ndarray, shape (n, n_c)) – Center eigenvectors stacked column-wise.

Raises:

numpy.linalg.LinAlgError – If eigenvalue decomposition fails. Returns empty arrays in this case.

Return type:

Tuple[ndarray, ndarray, ndarray, ndarray, ndarray, ndarray]

Notes

  • Eigenvectors are pivot-normalized: first non-zero entry equals 1

  • Small imaginary parts (< 1e-14) are set to zero for numerical stability

  • Empty subspaces return zero-column matrices with correct dimensions

Examples

>>> import numpy as np
>>> from hiten.algorithms.common.linalg import eigenvalue_decomposition
>>> # Continuous-time system with stable, center, unstable eigenvalues
>>> A = np.diag([-2.0, 0.0, 0.5])
>>> sn, un, cn, Ws, Wu, Wc = eigenvalue_decomposition(A)
>>> sn
array([-2.])
>>> un
array([0.5])
>>> cn
array([0.])

See also

eigenvalue_decomposition()

General eigenvalue classification

stability_indices(M, tol=1e-08)[source]

Compute Floquet stability indices for periodic orbit analysis.

Calculates the three stability indices nu_i = (lambda_i + 1/lambda_i)/2 from the monodromy matrix of a periodic orbit. For symplectic systems, eigenvalues occur in reciprocal pairs (lambda, 1/lambda), and this function explicitly searches for such pairs.

Parameters:

  • M (numpy.ndarray, shape (6, 6)) – Monodromy matrix from one-period state transition matrix integration. Expected to be symplectic for CR3BP applications.

  • tol (float, optional) – Tolerance for reciprocal eigenvalue pairing and unit-magnitude detection. Default is 1e-8.

Returns:

  • nu (numpy.ndarray, shape (3,)) – Stability indices nu_i = (lambda_i + 1/lambda_i)/2. Contains np.nan for unpaired eigenvalues.

  • eigvals (numpy.ndarray, shape (6,)) – Eigenvalues sorted by decreasing magnitude.

  • eigvecs (numpy.ndarray, shape (6, 6)) – Corresponding eigenvectors.

Raises:
Return type:

Tuple[ndarray, ndarray, ndarray]

Notes

  • Assumes symplectic structure with reciprocal eigenvalue pairs

  • Robust to small numerical symmetry-breaking errors

  • Identifies trivial pairs (magnitude near 1) first

  • Warns if expected number of pairs (3) cannot be found

For stable periodic orbits, all |nu_i| should be <= 1.

Examples

>>> import numpy as np
>>> from hiten.algorithms.linalg import _stability_indices
>>> # Identity matrix (trivial case)
>>> M = np.eye(6)
>>> nu, eigvals, eigvecs = _stability_indices(M)
>>> np.allclose(nu, 1.0)
True

See also

eigenvalue_decomposition()

General eigenvalue classification