Batch 8 of expansion-v2. Adds the state-estimation and model-reduction control
layers, surfaces coefficient uncertainty in the CLI, and reaches the TS SDK.
Deterministic/offline/std-only (Rust) or typed/tested (TS).
crates/lawsynth-estimate (new): Luenberger observer + steady-state continuous
Kalman filter for discovered linear models, derived as the exact dual of
lawsynth-feedback (place_poles/lqr on (Aᵀ,Cᵀ)). Coupled plant+observer RK4
proves ‖x−x̂‖→0 from a wrong initial estimate reconstructing unmeasured states
from partial measurements; Kalman CARE residual ~4e-16. Observability enforced;
error spectrum verified via koopman::eigen. 33 tests.
crates/lawsynth-modelreduce (new): balanced truncation. Gramians via Kronecker
Lyapunov solve, square-root (Laub) balancing, Hankel-SV truncation with the
2·Σσ a priori bound. HSV analytic match to 1e-12, Lyapunov residual <1e-12,
monotone full-vs-reduced response error, stability preserved. 23 tests.
crates/lawsynth-discovery + lawsynth-cli: `discover --bootstrap N [--confidence
C]` now computes and reports per-coefficient bootstrap CIs + inclusion
probability (text + --json), reusing lawsynth-uncertainty. Hooked in the shared
driver so single-node and partitioned paths agree; content-derived deterministic
seed; default path byte-identical. Closes the gap the docs surfaced. Discovery
41 lib + CLI 101 lib tests.
packages/world-schema + api-client: typed models + runtime parsers mirroring the
engine's stability/control/domains --json exactly (classification strings
confirmed against source + live output). Parsers, not a fabricated HTTP route
(no such endpoint exists). 20 api-client tests + world-schema suite green.
specs/{state-estimation,model-reduction}: boundary specs; discovery-run
candidate contract notes coefficient uncertainty.
State-estimation boundary (v2-A)
This directory specifies deterministic state estimation — given a
linear(ized) system with a partial output map, designing and running an
estimator that reconstructs the full state from partial, noisy measurements,
implemented in crates/lawsynth-estimate. It is a boundary specification in
the house style: it states what a conforming implementation MUST do, and —
crucially — what an estimator is and is not allowed to claim.
Motivation
A discovered dynamical law linearized at a fixed point is ẋ = A x + B u with
A = ∂f/∂x the Jacobian (the object crates/lawsynth-stability classifies and
crates/lawsynth-feedback controls). In practice not every state is measured:
sensing produces an output y = C x, where C (p × n) selects or mixes
the observed states. When p < n the state is only partially observed.
The estimation question is then: reconstruct the full x from the stream of
y (and the known input u). The standard device is an observer, a copy of
the model corrected by the measurement residual (the innovation y − C x̂):
x̂̇ = A x̂ + B u + L (y − C x̂), so the error e = x − x̂ obeys ė = (A − L C) e.
Choosing the gain L so A − L C is Hurwitz makes x̂ → x. Two classical
answers:
- Luenberger observer / pole placement puts the error eigenvalues at chosen locations (a desired estimation decay rate). For a single output it is solved exactly by Ackermann's formula.
- Kalman filter instead chooses
Loptimally given a stochastic model — process covarianceQand measurement covarianceR. The steady-state continuous gain isL = P Cᵀ R⁻¹, wherePsolves the filter continuous algebraic Riccati equation (CARE)A P + P Aᵀ − P Cᵀ R⁻¹ C P + Q = 0.
Duality (why this reuses the feedback crate)
Estimator design is the exact dual of feedback design, because
(A − L C)ᵀ = Aᵀ − Cᵀ Lᵀ. Placing the error poles of (A, C) is placing the
feedback poles of (Aᵀ, Cᵀ); the optimal filter is the LQR of (Aᵀ, Cᵀ). So
this crate reuses crates/lawsynth-feedback rather than re-deriving numerics:
- Observer
L = place_poles(Aᵀ, Cᵀ, desired)ᵀ. With a single output,Cᵀisn × 1— the SISO case Ackermann handles. - Kalman
L = lqr(Aᵀ, Cᵀ, Q, R)ᵀ. The feedback CAREAᵀP + PA − PBR⁻¹BᵀP + Q = 0, under(A, B) → (Aᵀ, Cᵀ), becomes exactly the filter CARE above with solutionX = P; its gainR⁻¹ C Ptransposes toP Cᵀ R⁻¹. The feedback crate's CARE convention therefore maps to the filter CARE with no sign or transpose adjustment — the substitution is direct.
LawSynth is deterministic and offline. This stage reuses the deterministic
eigensolver of crates/lawsynth-koopman (Householder–Hessenberg + Wilkinson
complex QR) to report the achieved error spectrum eigen(A − L C), and the
deterministic Ackermann / Kleinman–Riccati machinery of crates/lawsynth-feedback
for the gains. Identical inputs MUST yield bit-identical output.
What an estimator IS
An estimator is a property of the supplied linear triple (A, C) (plus the
design targets or covariances), not of any data or of the underlying nonlinear
field. The contract is:
- A gain for the linearization, not the nonlinear law.
Lshapes the error dynamicsA − L C. On the true nonlinear system the estimate is valid only in the neighbourhood of the fixed point whereAis a faithful linearization; the crate makes no global reconstruction claim. - Exact placement, honestly verified. The observer returns the achieved
error poles as
eigen(A − L C), so a caller reads the actually realized spectrum — not merely the requested one — and can see any numerical drift. - The Riccati solution is checkable. The Kalman filter returns the solved
error covariance
P; plugging it back into the filter CARE gives a residual a caller can measure. The optimality claim is exactly "this(L, P)is a stabilizing solution of the stated filter CARE", no more. - A property of the expression, not of any fit. The design carries no discovery confidence or fit residual. Those are separate, upstream concerns.
Requirements
-
Observer placement is single-output and exact (dual Ackermann). For an observable pair
(A, C)withCof shape1 × nandndesired error poles, an implementation MUST computeL = place_poles(Aᵀ, Cᵀ, desired)ᵀ, reusing the feedback crate's Ackermann routine on the dual pair, never a re-derived formula. A tallerC(p > 1) MUST be rejected with a distinctMultiOutputerror. -
Real gains only. The desired error poles MUST be closed under complex conjugation, so the placement polynomial is real and
Lis real. A lone complex pole MUST be rejected (NonRealDesignPoles), inherited from the dual placement, rather than returning a complex gain. -
Observability is required, not assumed. The observability matrix
O = [C; CA; …; CAⁿ⁻¹](np × n) MUST have full column rankn, checked by deterministic Gaussian elimination (largest-magnitude pivot, lowest index on a tie). A rank-deficient pair is unobservable and MUST return a distinctUnobservableerror — the dual of an uncontrollable feedback pair — never a fabricated gain. -
The Kalman filter solves the filter CARE by the dual LQR. For covariances
Q ⪰ 0(process) andR ≻ 0(measurement), an implementation MUST compute(L, P)fromlqr(Aᵀ, Cᵀ, Q, R): the returned Riccati matrix is the error covariancePandL = (lqr gain)ᵀ = P Cᵀ R⁻¹. The underlying solve MUST be the feedback crate's deterministic Kleinman iteration (exact vectorized Lyapunov steps), not a second scheme, andPMUST be symmetric. The Kalman path admits multiple outputs (p ≥ 1), since the dual LQR is multi-input. -
Covariances are validated at the boundary.
QMUST be symmetric and positive semidefinite;RMUST be symmetric and positive definite (hence invertible). Violations MUST surface as distinct typed errors (NotSymmetric,NotPositiveSemidefinite,NotPositiveDefinite), inherited from the dual LQR, never a silently repaired covariance. A non-detectable pair (the dual of non-stabilizable) MUST return a distinctNotDetectableerror. -
Reuse the deterministic eigensolver. The achieved error poles MUST come from the
lawsynth-koopmaneigensolver applied toA − L C, in that solver's canonical order, so the whole pipeline shares one audited decomposition. -
Simulation integrates the coupled system with fixed-step RK4. The estimator demonstration MUST integrate the plant
ẋ = A x + B uand the observerx̂̇ = A x̂ + B u + L (y − C x̂)together with a fixed-step classical RK4, from a caller-supplied (possibly wrong) initial estimatex̂(0) ≠ x(0), returning both trajectories, the recorded measurementsy = C x (+ noise), and the estimation error‖x − x̂‖₂over time. Inputs and any measurement noise are held over each step (zero-order hold). -
Any noise is seeded and deterministic. Optional measurement noise MUST be drawn from the project's SplitMix64 generator (
lawsynth_core::DeterministicRng) shaped by Box–Muller, seeded from a fixedu64— never the wall clock. -
Determinism. Observability, dual placement / LQR, the eigen-verification, RK4 integration, and seeded noise MUST all be deterministic. Identical inputs MUST produce a bit-identical result: identical gain
L, covarianceP, and trajectories (tof64bit patterns), and an identical error-pole set in identical order.
Public API
design_observer(&Matrix /*A*/, &Matrix /*C, 1×n*/, &[Complex] /*error poles*/)
-> Result<Observer, EstimateError>
kalman_filter(&Matrix /*A*/, &Matrix /*C, p×n*/, &Matrix /*Q, n×n*/, &Matrix /*R, p×p*/)
-> Result<Observer, EstimateError>
run_observer(&Observer, &Matrix /*A*/, &Matrix /*B*/, &Matrix /*C*/,
&[f64] /*true x0*/, &[f64] /*est x0*/, &[Vec<f64>] /*inputs*/,
Option<MeasurementNoise>, f64 /*dt*/, usize /*steps*/)
-> Result<EstimateTrajectory, EstimateError>
observability_matrix(&Matrix, &Matrix) -> Result<Matrix, EstimateError>
is_observable(&Matrix, &Matrix) -> Result<bool, EstimateError>
Observer { gain: Matrix, error_poles: Vec<Complex>, covariance: Option<Matrix>,
method: ObserverMethod }
Observer::is_convergent(margin) -> bool
EstimateTrajectory { times, true_states, estimates, measurements, errors }
MeasurementNoise { seed, std_dev }
Matrix and Complex are re-exported from lawsynth-koopman so a caller builds
(A, B, C) and reads error poles / covariance without a separate dependency. The
observer returns covariance: None (it forms no covariance); the Kalman filter
returns Some(P). This crate delivers the estimation library only; wiring it
into a controller (the separation principle), a discovery report, or a live sensor
loop is downstream and out of scope here.
Honest scope & limits
- Observer placement is single-output only. Dual Ackermann applies to one
measured output (
Cof height 1). Multi-output placement has extra freedom that must be resolved by a robustness criterion (dual Kautsky–Nichols / robust eigenstructure assignment); that is deliberately not implemented, and a tallerCis rejected rather than silently reduced. The Kalman filter does handle multiple outputs, via the multi-input dual LQR. - Kalman is steady-state and continuous-time only. This is the infinite-horizon continuous filter (a constant gain from the CARE). There is no time-varying Riccati, no discrete-time (DARE) filter, and no extended / unscented filter for nonlinear models — the estimate is linear and local to the linearization.
- Optimality is Gaussian and asymptotic. The Kalman gain is optimal only
under the linear-Gaussian assumptions (white
Q,R) at steady state; the returnedPis the steady-state error covariance, and the CARE residual is a modelling check, not a proof of optimality to machine precision. - Detectability and
R ≻ 0are assumed. The dual LQR needs a stabilizing solution; a non-detectable pair (an unstable, unobservable mode) has none and is reported as such.Rmust be positive definite forR⁻¹to exist. - The estimate is only as local as the linearization.
Ais a Jacobian at a point; convergencex̂ → xis guaranteed for the linear error dynamics, not for the true nonlinear flow away from the fixed point. - Numerical conditioning degrades near the edges. For large
n, a near-unobservable pair, or a fast desired error spectrum, the observability matrix, the placement polynomial, and then² × n²Lyapunov system become ill-conditioned; the achieved error poles then drift from the requested ones, which is precisely why the achieved spectrum is reported rather than assumed. RK4 integration adds a fixed-step truncation error to the simulated trajectories.
Non-goals
- No multi-output / robust observer placement, no reduced-order (Gopinath) observer, no unknown-input or disturbance observer.
- No discrete-time filter (DARE), no time-varying / finite-horizon Kalman, no extended, unscented, or particle filtering for nonlinear models.
- No separation-principle controller synthesis (combining an observer with a feedback gain), no output-feedback design — estimation only.
- No region-of-attraction estimate or any nonlinear / global reconstruction guarantee for the underlying field.