[AUD-013][High] Report Gramian non-convergence instead of returning zero

[gabrielsantosphilips]

Audit finding

• ID: AUD-013
• Status: Verified defect
• Severity: High
• Confidence: High
• Audited revision: 2f479320d805a1f9f35ebe4afaaeeded48913a94

Problem

The discrete Lyapunov iteration has a fixed 200-iteration budget and returns an all-zero matrix when it does not converge. Zero is also a valid Gramian, so callers cannot distinguish failure.

Source:

numerical-toolbox-cpp/numerical/control_analysis/ControllabilityObservability.hpp

Lines 189 to 221 in 2f47932

	constexpr std::size_t maxIter{ 200 };
	constexpr T convTol{ T(1e-6) };
	constexpr T divergenceBound{ T(1e18) };
	SquareMatrix X{ Q };
	SquareMatrix At{ A.Transpose() };
	for (std::size_t iter = 0; iter < maxIter; ++iter)
	{
	SquareMatrix Xnext{ A * X * At + Q };
	if (MaxAbsValue(Xnext) > divergenceBound)
	return SquareMatrix{};
	if (MaxAbsDiff(Xnext, X) < convTol)
	return Xnext;
	X = Xnext;
	}
	return SquareMatrix{};
	}
	template<typename T, std::size_t n, std::size_t m, std::size_t p>
	OPTIMIZE_FOR_SPEED typename ControllabilityObservability<T, n, m, p>::SquareMatrix
	ControllabilityObservability<T, n, m, p>::ControllabilityGramian(const LTI& plant)
	{
	return SolveDiscreteLyapunov(plant.A, plant.B * plant.B.Transpose());
	}
	template<typename T, std::size_t n, std::size_t m, std::size_t p>
	OPTIMIZE_FOR_SPEED typename ControllabilityObservability<T, n, m, p>::SquareMatrix
	ControllabilityObservability<T, n, m, p>::ObservabilityGramian(const LTI& plant)
	{
	return SolveDiscreteLyapunov(plant.A.Transpose(), plant.C.Transpose() * plant.C);
	}

Reproduction

For scalar stable A=0.99, B=1, the exact controllability Gramian is 1/(1-0.99^2) = 50.2513. Production returns zero after iteration exhaustion.

Acceptance criteria

• Return convergence status separately from the Gramian value.
• Use a robust Lyapunov solver or a scale-aware convergence strategy for near-unit stable systems.
• Never encode non-convergence as a valid zero matrix.
• Add analytic scalar references approaching the unit circle.