Skip to content

Commit dcbd55c

Browse files
feat: add spectral radius (#197)
* add spectral radius * Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
1 parent bc51f7c commit dcbd55c

9 files changed

Lines changed: 280 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@ Refer to the documentation to quickly integrate and utilize the library's signal
2626
| [Neural Network](doc/neural_network/README.md) | Layers, activations, losses, model |
2727
| [Optimization](doc/optimization/README.md) | Gradient Descent |
2828
| [Regularization](doc/regularization/README.md) | L1 (Lasso), L2 (Ridge) |
29-
| [Math](doc/math/README.md) | CORDIC, Quaternion, MatrixNorms, Step Response Metrics |
30-
| [Solvers](doc/solvers/README.md) | Gaussian Elimination, Levinson-Durbin, Durand-Kerner, Cholesky, DARE, Runge-Kutta ODE Integrators (RK4 + Dormand-Prince), Condition Number |
29+
| [Math](doc/math/README.md) | CORDIC, Quaternion, MatrixNorms, Step Response Metrics |
30+
| [Solvers](doc/solvers/README.md) | Gaussian Elimination, Levinson-Durbin, Durand-Kerner, Cholesky, DARE, Runge-Kutta ODE Integrators (RK4 + Dormand-Prince), Spectral Radius & Discrete Stability Margin |
3131
| [Performance Optimization](doc/performance-optimization/README.md) | Compiler optimizations, SIMD |
3232

3333
Each category page lists its algorithms with a brief description and links to the detailed documentation.

‎ROADMAP.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,6 @@ Difficulty legend:
4848
| 45 | IIR filter design (Butterworth/Chebyshev + bilinear) | `filters/passive` | ★★★★★ |
4949
| 46 | H∞ state-feedback control | `robust_control` (new) | ★★★★★ |
5050
| 47 | Model Reference Adaptive Control (MRAC) | `nonlinear_control` (new) | ★★★★★ |
51-
| 51 | Spectral radius / discrete stability margin | `math` | ★★★☆☆ |
5251
| 52 | Estimator consistency metrics (NEES / NIS) | `estimators` | ★★★☆☆ |
5352

5453
Items 48–52 are the **evaluation & metrics primitives** — reusable quantities the per-family

‎doc/solvers/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,5 @@ Numerical solvers for linear systems, polynomial roots, and matrix equations.
1212
| [Durand-Kerner](DurandKerner.md) | Simultaneous iterative root-finder for polynomials |
1313
| [Discrete Algebraic Riccati Equation](DiscreteAlgebraicRiccatiEquation.md) | Iterative solver for the DARE arising in LQR and Kalman filter design |
1414
| [Runge-Kutta ODE Integrators](RungeKuttaIntegrators.md) | Fixed-step RK4 and adaptive Dormand-Prince RK45 for ODE integration |
15+
| [Spectral Radius](SpectralRadius.md) | Dominant eigenvalue magnitude and discrete-time Schur stability margin |
1516
| [Condition Number](ConditionNumber.md) | 1-norm condition number estimate via column-wise inverse solve |

‎doc/solvers/SpectralRadius.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Spectral Radius & Discrete Stability Margin
2+
3+
## Overview & Motivation
4+
5+
The spectral radius of a square matrix is the largest magnitude among all its eigenvalues. In discrete-time dynamical systems, the spectral radius of the state-transition matrix is the single most important scalar quantity: if it is strictly less than one, every state trajectory converges to zero; if it equals or exceeds one, at least one mode grows without bound or fails to decay. Rather than reporting only a binary stable/unstable flag, exposing the spectral radius and the complementary stability margin (one minus the spectral radius) gives the designer a quantitative handle on how much gain or perturbation the system can tolerate before losing stability.
6+
7+
## Mathematical Theory
8+
9+
### Characteristic Polynomial via Faddeev–LeVerrier
10+
11+
Given an $n \times n$ matrix $A$, the characteristic polynomial is
12+
13+
$$p(\lambda) = \det(\lambda I - A) = \lambda^n + c_{n-1}\lambda^{n-1} + \cdots + c_1\lambda + c_0.$$
14+
15+
The Faddeev–LeVerrier recurrence computes the coefficients $c_k$ without determinant expansion. Define auxiliary matrices $M_k$ by
16+
17+
$$M_1 = A, \quad c_{n-1} = -\operatorname{tr}(M_1),$$
18+
$$M_k = A\bigl(M_{k-1} + c_{n-k+1}I\bigr), \quad c_{n-k} = -\frac{1}{k}\operatorname{tr}(M_k), \quad k = 2, \ldots, n.$$
19+
20+
This recurrence requires only matrix-matrix multiplication, scalar multiplication of a matrix by the identity, and the trace, making it suitable for static (stack-allocated) computation without a heap.
21+
22+
### Spectral Radius
23+
24+
Given the full set of eigenvalues $\{\lambda_i\}_{i=1}^{n}$ (roots of the characteristic polynomial),
25+
26+
$$\rho(A) = \max_{i} |\lambda_i|.$$
27+
28+
The roots are found numerically with the Durand–Kerner simultaneous root-finding iteration, which converges for arbitrary polynomials and requires only a fixed-size array of complex iterates.
29+
30+
### Schur Stability
31+
32+
A matrix $A$ is Schur-stable (the discrete-time analogue of Hurwitz stability) if and only if $\rho(A) < 1$. Every eigenvalue then lies strictly inside the complex unit disk, guaranteeing exponential decay of all modes.
33+
34+
### Stability Margin
35+
36+
$$\delta(A) = 1 - \rho(A).$$
37+
38+
A positive margin indicates Schur stability; $\delta = 0$ corresponds to marginal stability (an eigenvalue on the unit circle); $\delta < 0$ signals instability. The margin quantifies how far $\rho(A)$ is from the stability boundary.
39+
40+
## Complexity Analysis
41+
42+
| Case | Time | Space | Notes |
43+
|---------|-----------------------------|--------------|-----------------------------------------------------------------------|
44+
| Best | $O(n^3)$ | $O(n^2)$ | Faddeev–LeVerrier dominates; two $n\times n$ temporaries on the stack |
45+
| Average | $O(n^3 + n \cdot I)$ | $O(n^2 + n)$ | $I$ Durand–Kerner iterations, typically $\ll 200$ |
46+
| Worst | $O(n^3 + n \cdot I_{\max})$ | $O(n^2 + n)$ | Near-repeated roots slow DK convergence |
47+
48+
The Faddeev–LeVerrier step executes $n$ matrix multiplications each costing $O(n^3)$, giving $O(n^4)$ total; for the small dimensions typical of embedded control matrices ($n \le 6$) this is negligible.
49+
50+
## Step-by-Step Walkthrough
51+
52+
Consider $A = \begin{pmatrix} 0 & -1 \\ 1 & 0 \end{pmatrix}$ (90° rotation, $\rho = 1$).
53+
54+
1. **k = 1**: $M_1 = A \cdot 0 + I \cdot c_0$. With $c_0 = 1$: $M_1 = I$. Then $c_1 = -\tfrac{1}{1}\operatorname{tr}(A \cdot M_1) = -\operatorname{tr}(A) = 0$.
55+
2. **k = 2**: $M_2 = A(M_1 + c_1 I) = A \cdot I = A$. Then $c_2 = -\tfrac{1}{2}\operatorname{tr}(A \cdot A) = -\tfrac{1}{2}\operatorname{tr}(-I) = 1$.
56+
57+
Characteristic polynomial: $\lambda^2 + 0\lambda + 1 = \lambda^2 + 1$. Roots: $\pm i$, magnitudes both 1. $\rho = 1$.
58+
59+
## Pitfalls & Edge Cases
60+
61+
- **Near-repeated roots**: Durand–Kerner converges slowly when two or more eigenvalues are nearly identical. The stability conclusion (inside/outside unit disk) is unaffected, but the raw $\rho$ value may have larger numerical error.
62+
- **Identity approximation in Matrix::Identity()**: This implementation builds its own exact identity to avoid reliance on library internals.
63+
- **Ill-conditioned characteristic polynomials**: For large $n$ the polynomial coefficients can have widely different magnitudes, degrading root-finder precision. The algorithm is intended for small matrices ($n \le 6$) typical of discrete-time state-space models.
64+
- **Size = 1 case**: Handled directly as $\rho = |a_{11}|$, bypassing polynomial computation.
65+
- **Zero matrix**: $\rho = 0$, $\delta = 1$ (maximally stable). Handled correctly by the recurrence.
66+
67+
## Variants & Generalizations
68+
69+
- **Power iteration** computes only the dominant eigenvalue magnitude without the full spectrum; cheaper for large $n$ but provides no stability margin without additional eigenpair deflation.
70+
- **QR algorithm** (Jacobi, Hessenberg QR) finds all eigenvalues more robustly for large or symmetric matrices; too expensive and heap-dependent for small embedded targets.
71+
- **Continuous-time analogue**: Replace the unit-disk criterion with the left half-plane criterion; Routh–Hurwitz or Lyapunov-based approaches apply.
72+
73+
## Applications
74+
75+
- Verifying discrete-time state-feedback or observer designs remain within the unit disk after coefficient quantisation.
76+
- Checking closed-loop stability after LQR or pole-placement synthesis before deployment.
77+
- Computing gain/phase margins indirectly by perturbing the loop gain and re-evaluating $\rho$.
78+
- Monitoring on-line whether a time-varying system's frozen eigenvalues have drifted outside the unit disk.
79+
80+
## Connections to Other Algorithms
81+
82+
- Uses **Durand–Kerner** (polynomial root-finder) for the eigenvalue computation stage.
83+
- The characteristic polynomial recurrence is mathematically related to **Leverrier's method** for matrix inverses and adjoints.
84+
- The Schur-stability criterion is the discrete-time counterpart of the Hurwitz criterion used in continuous-time control analysis.
85+
- The stability margin scalar is a prerequisite for **TESTING.md** evaluation metrics that require a quantitative stability distance.
86+
87+
## References & Further Reading
88+
89+
- Faddeev, D. K. & LeVerrier, U. J. F. — classical matrix identity; see G. H. Golub & C. F. Van Loan, *Matrix Computations*, 4th ed., Section 7.3.
90+
- Durand, E. (1960) and Kerner, I. O. (1966) — simultaneous root-finding; see *Numerical Recipes in C*, 3rd ed., Section 9.5.
91+
- Schur stability: K. J. Åström & B. Wittenmark, *Computer-Controlled Systems*, 3rd ed., Chapter 3.

‎numerical/solvers/CMakeLists.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,15 @@ target_sources(numerical.solver PRIVATE
2121
OdeSystem.hpp
2222
RungeKuttaIntegrators.hpp
2323
Solver.hpp
24+
SpectralRadius.hpp
2425
)
2526

2627
numerical_add_coverage_sources(numerical.solver
2728
DiscreteAlgebraicRiccatiEquation.cpp
2829
DurandKerner.cpp
2930
GaussianElimination.cpp
3031
RungeKuttaIntegrators.cpp
32+
SpectralRadius.cpp
3133
)
3234

3335
add_subdirectory(test)
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#include "numerical/solvers/SpectralRadius.hpp"
2+
3+
namespace solvers
4+
{
5+
template class SpectralRadius<float, 3>;
6+
}
Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
#pragma once
2+
3+
#if defined(__GNUC__) || defined(__clang__)
4+
#pragma GCC optimize("O3", "fast-math")
5+
#endif
6+
7+
#include "numerical/math/CompilerOptimizations.hpp"
8+
#include "numerical/math/Matrix.hpp"
9+
#include "numerical/solvers/DurandKerner.hpp"
10+
#include <array>
11+
#include <cmath>
12+
#include <cstddef>
13+
#include <span>
14+
#include <type_traits>
15+
16+
namespace solvers
17+
{
18+
template<typename T, std::size_t Size>
19+
class SpectralRadius
20+
{
21+
static_assert(std::is_floating_point_v<T>,
22+
"SpectralRadius supports floating-point types only");
23+
24+
public:
25+
OPTIMIZE_FOR_SPEED T Compute(const math::SquareMatrix<T, Size>& matrix) const;
26+
OPTIMIZE_FOR_SPEED bool IsSchurStable(const math::SquareMatrix<T, Size>& matrix) const;
27+
OPTIMIZE_FOR_SPEED T StabilityMargin(const math::SquareMatrix<T, Size>& matrix) const;
28+
29+
private:
30+
static OPTIMIZE_FOR_SPEED math::SquareMatrix<T, Size> MakeIdentity();
31+
static OPTIMIZE_FOR_SPEED std::array<T, Size + 1> CharacteristicPolynomial(const math::SquareMatrix<T, Size>& matrix);
32+
};
33+
34+
template<typename T, std::size_t Size>
35+
math::SquareMatrix<T, Size> SpectralRadius<T, Size>::MakeIdentity()
36+
{
37+
math::SquareMatrix<T, Size> result{};
38+
for (std::size_t i = 0; i < Size; ++i)
39+
result.at(i, i) = T(1);
40+
return result;
41+
}
42+
43+
template<typename T, std::size_t Size>
44+
std::array<T, Size + 1> SpectralRadius<T, Size>::CharacteristicPolynomial(const math::SquareMatrix<T, Size>& matrix)
45+
{
46+
std::array<T, Size + 1> coefficients{};
47+
coefficients[0] = T(1);
48+
49+
math::SquareMatrix<T, Size> M{};
50+
const math::SquareMatrix<T, Size> identity = MakeIdentity();
51+
52+
for (std::size_t k = 1; k <= Size; ++k)
53+
{
54+
M = matrix * M + identity * coefficients[k - 1];
55+
coefficients[k] = -(matrix * M).Trace() / static_cast<T>(k);
56+
}
57+
58+
return coefficients;
59+
}
60+
61+
template<typename T, std::size_t Size>
62+
T SpectralRadius<T, Size>::Compute(const math::SquareMatrix<T, Size>& matrix) const
63+
{
64+
if constexpr (Size == 1)
65+
return std::abs(matrix.at(0, 0));
66+
67+
const std::array<T, Size + 1> poly = CharacteristicPolynomial(matrix);
68+
69+
DurandKerner<T, Size> solver{};
70+
auto roots = solver.Solve(std::span<const T>{ poly.data(), poly.size() });
71+
72+
T rho{};
73+
for (std::size_t i = 0; i < roots.size(); ++i)
74+
{
75+
T magnitude = std::abs(roots[i]);
76+
if (magnitude > rho)
77+
rho = magnitude;
78+
}
79+
80+
return rho;
81+
}
82+
83+
template<typename T, std::size_t Size>
84+
bool SpectralRadius<T, Size>::IsSchurStable(const math::SquareMatrix<T, Size>& matrix) const
85+
{
86+
return Compute(matrix) < T(1);
87+
}
88+
89+
template<typename T, std::size_t Size>
90+
T SpectralRadius<T, Size>::StabilityMargin(const math::SquareMatrix<T, Size>& matrix) const
91+
{
92+
return T(1) - Compute(matrix);
93+
}
94+
95+
#ifdef NUMERICAL_TOOLBOX_COVERAGE_BUILD
96+
extern template class SpectralRadius<float, 3>;
97+
#endif
98+
}

‎numerical/solvers/test/CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,5 @@ target_sources(numerical.solvers_test PRIVATE
1414
TestGaussianElimination.cpp
1515
TestLevinsonDurbin.cpp
1616
TestRungeKuttaIntegrators.cpp
17+
TestSpectralRadius.cpp
1718
)
Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
#include "numerical/math/Tolerance.hpp"
2+
#include "numerical/solvers/SpectralRadius.hpp"
3+
#include <gtest/gtest.h>
4+
#include <numbers>
5+
6+
namespace
7+
{
8+
class TestSpectralRadius : public ::testing::Test
9+
{
10+
protected:
11+
solvers::SpectralRadius<float, 3> solver3;
12+
solvers::SpectralRadius<float, 2> solver2;
13+
solvers::SpectralRadius<float, 1> solver1;
14+
};
15+
}
16+
17+
TEST_F(TestSpectralRadius, diagonal_matrix_rho_equals_largest_magnitude_diagonal)
18+
{
19+
math::SquareMatrix<float, 3> A{ { 1.0f, 0.0f, 0.0f }, { 0.0f, 2.0f, 0.0f }, { 0.0f, 0.0f, 3.0f } };
20+
21+
float rho = solver3.Compute(A);
22+
23+
EXPECT_NEAR(rho, 3.0f, 1e-2f);
24+
}
25+
26+
TEST_F(TestSpectralRadius, known_matrix_rho_matches_analytic_dominant_eigenvalue)
27+
{
28+
math::SquareMatrix<float, 3> A{ { 3.0f, 1.0f, 0.0f }, { 0.0f, 2.0f, 0.0f }, { 0.0f, 0.0f, 1.0f } };
29+
30+
float rho = solver3.Compute(A);
31+
32+
EXPECT_NEAR(rho, 3.0f, 1e-2f);
33+
}
34+
35+
TEST_F(TestSpectralRadius, complex_conjugate_pair_rho_equals_modulus)
36+
{
37+
float r = 0.5f;
38+
float theta = std::numbers::pi_v<float> / 4.0f;
39+
math::SquareMatrix<float, 2> A{
40+
{ r * std::cos(theta), -r * std::sin(theta) },
41+
{ r * std::sin(theta), r * std::cos(theta) }
42+
};
43+
44+
float rho = solver2.Compute(A);
45+
46+
EXPECT_NEAR(rho, r, 1e-2f);
47+
}
48+
49+
TEST_F(TestSpectralRadius, schur_stable_true_when_all_eigenvalues_inside_unit_disk)
50+
{
51+
math::SquareMatrix<float, 3> A{ { 0.5f, 0.0f, 0.0f }, { 0.0f, 0.3f, 0.0f }, { 0.0f, 0.0f, 0.1f } };
52+
53+
EXPECT_TRUE(solver3.IsSchurStable(A));
54+
}
55+
56+
TEST_F(TestSpectralRadius, schur_stable_false_when_eigenvalue_outside_unit_disk)
57+
{
58+
math::SquareMatrix<float, 3> A{ { 0.5f, 0.0f, 0.0f }, { 0.0f, 1.1f, 0.0f }, { 0.0f, 0.0f, 0.1f } };
59+
60+
EXPECT_FALSE(solver3.IsSchurStable(A));
61+
}
62+
63+
TEST_F(TestSpectralRadius, stability_margin_equals_one_minus_rho)
64+
{
65+
math::SquareMatrix<float, 3> A{ { 0.5f, 0.0f, 0.0f }, { 0.0f, 0.3f, 0.0f }, { 0.0f, 0.0f, 0.1f } };
66+
67+
float margin = solver3.StabilityMargin(A);
68+
69+
EXPECT_NEAR(margin, 0.5f, 1e-2f);
70+
}
71+
72+
TEST_F(TestSpectralRadius, scalar_size_one_rho_equals_absolute_value_of_entry)
73+
{
74+
math::SquareMatrix<float, 1> A{ { -3.0f } };
75+
76+
float rho = solver1.Compute(A);
77+
78+
EXPECT_NEAR(rho, 3.0f, math::Tolerance<float>());
79+
}

0 commit comments

Comments
 (0)