Batch 6 of expansion-v2. Makes the new engine reachable from the CLI and adds
the dynamics analysis layer on top of it. Deterministic/offline/std-only.
lawsynth-cli: exposes the just-built engine crates as real, tested commands.
- `lawsynth stability WORLD --box LOW:HIGH` — fixed points + eigenvalues +
classification (honest marginal/no-root/seed accounting).
- `lawsynth control OBS.csv --state.. --control.. [--validate]` — SINDYc
controlled discovery + in-sample R²/RMSE (dedicated subcommand so
discover's .lsworld contract stays clean).
- `lawsynth domains [show|run NAME]` — list/inspect/round-trip presets.
- `discover` template-prior flags (--max-degree/--allow-vars/--allow-kinds/
--forbid-interactions/--max-active/--require-kind) with honest drop report.
- `simplify` upgraded to the egraph simplify_law pass.
101 unit + 8 new end-to-end integration tests.
crates/lawsynth-bifurcation (new): parameter continuation + bifurcation
detection on a discovered field f(x;μ). Deterministic grid sweep, proximity
branch matching, eigenvalue-crossing detection with bisection localization.
Detects saddle-node/transcritical/pitchfork (generic Fold) and Hopf at μ*≈0 on
the textbook normal forms. 32 tests.
crates/lawsynth-feedback (new): linear feedback design from a discovered
linearization (A,B). Ackermann SISO pole placement (double integrator → exact
K, poles matched <1e-10) and LQR via Kleinman/Bass Riccati iteration
(analytic K=[1,√3], CARE residual ~4e-16). Closed-loop poles verified through
koopman::eigen. 28 tests.
crates/lawsynth-uncertainty: deterministic bootstrap for discovered
coefficients — per-term CIs + inclusion probability. True terms hit inclusion
1.0 with covering CIs, spurious 0.0; CI width shrinks ~4x with n. Reuses the
crate's SplitMix64, seeded per replicate by (seed,b). 24 tests.
specs/{bifurcation-analysis,control-design,coefficient-uncertainty}: boundary
specs with honest limits (grid-bounded continuation, SISO/continuous-time
feedback, approximate bootstrap CIs under time correlation).
Control-design boundary (v2-A)
This directory specifies deterministic linear state-feedback design — given a
linear(ized) system, computing a gain K that stabilizes it or makes it optimal
in the LQR sense, implemented in crates/lawsynth-feedback. It is a boundary
specification in the house style: it states what a conforming implementation
MUST do, and — crucially — what a designed gain is and is not allowed to claim.
Motivation
A discovered dynamical law is an autonomous vector field ẋ = f(x). Near a fixed
point x*, its behaviour is governed by the linearization ẋ = A x with
A = ∂f/∂x the Jacobian at x* (the same object crates/lawsynth-stability
classifies). If the system additionally admits actuation — a control input u
entering through an input matrix B — the linearized, actuated dynamics are
ẋ = A x + B u.
The engineering question is then: choose a state-feedback law u = −K x so
the closed loop ẋ = (A − B K) x behaves as desired. Two classical answers:
- Pole placement puts the closed-loop eigenvalues at chosen locations. For a single input it is solved exactly by Ackermann's formula. This is the tool when the target spectrum is known (a desired decay rate, a damped oscillation).
- LQR (linear–quadratic regulator) instead minimizes the infinite-horizon
cost
∫₀^∞ (xᵀQx + uᵀRu) dt. Its optimal gain isK = R⁻¹BᵀP, wherePsolves the continuous-time algebraic Riccati equation (CARE)AᵀP + PA − PBR⁻¹BᵀP + Q = 0. This is the tool when the trade-off between state error and control effort is what is specified, not the poles themselves.
LawSynth is deterministic and offline. This stage reuses the deterministic
eigensolver of crates/lawsynth-koopman (Householder–Hessenberg + Wilkinson
complex QR) to report the achieved closed-loop spectrum; the only other numerics
are local Gaussian elimination, a Kronecker-form Lyapunov solve, and matrix
polynomials. Identical inputs MUST yield bit-identical output.
What a designed gain IS
A gain is a property of the supplied linear pair (A, B) and the design
weights, not of any data or of the underlying nonlinear field. The contract is:
- A gain for the linearization, not the nonlinear law.
KstabilizesA − B K. On the true nonlinear system it is valid only in the neighbourhood of the fixed point whereAis a faithful linearization (Hartman–Grobman); the crate makes no basin-of-attraction or global claim. - Exact placement, honestly verified. Pole placement returns the achieved
poles as
eigen(A − B K), so a caller reads the actually realized spectrum — not merely the requested one — and can see any numerical drift. - The Riccati solution is checkable. LQR returns the solved
P; plugging it back into the CARE gives a residual a caller can measure. The optimality claim is exactly "this(K, P)is a stabilizing solution of the stated 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
-
Pole placement is single-input and exact (Ackermann). For a controllable pair
(A, b)withbof shapen × 1andndesired poles, an implementation MUST computeK = eₙᵀ C⁻¹ p(A), whereC = [b, Ab, …, Aⁿ⁻¹b]is the controllability matrix,eₙᵀ = [0 … 0 1], andpis the monic desired characteristic polynomial∏(s − λᵢ).C⁻¹andp(A)MUST be formed with local deterministic Gaussian elimination and matrix multiplication. -
Real gains only. The desired poles MUST be closed under complex conjugation, so
phas real coefficients andKis real. An implementation MUST reject a pole set whose expanded polynomial retains an imaginary part above tolerance (a lone complex pole) rather than return a complex gain. -
Controllability is required, not assumed. If
Cis singular the pair is uncontrollable and no gain can place the poles; the implementation MUST return a distinctUncontrollableerror, never a fabricated or least-squares gain. -
LQR solves the CARE by a deterministic Kleinman iteration. From an initial stabilizing gain
K₀, each step MUST solve the Lyapunov equation(A − BKᵢ)ᵀ P + P (A − BKᵢ) = −(Q + KᵢᵀRKᵢ)and updateK = R⁻¹BᵀP, iterating to a fixed convergence tolerance. The Lyapunov step MUST be solved exactly by vectorization — the Kronecker system((I ⊗ Aᶜᵀ) + (Aᶜᵀ ⊗ I)) vec(P) = −vec(W)solved by local Gaussian elimination — not by a second iterative scheme. The returnedPMUST be symmetrized ((P + Pᵀ)/2), exact in infinite precision. -
The initial gain is constructed deterministically.
K₀MUST come from a fixed rule (Bass's algorithm: withβ > ‖A‖, solve(A + βI) Z + Z (A + βI)ᵀ = 2BBᵀand setK₀ = BᵀZ⁻¹), never from a random seed or an eigenvalue guess. If no stabilizingK₀can be built the implementation MUST return a distinctNotStabilizableerror. -
Weights are validated at the boundary.
QMUST be symmetric and positive semidefinite;RMUST be symmetric and positive definite (hence invertible). Symmetry is checked directly; definiteness is checked from the shared eigensolver's eigenvalues. A violated precondition MUST surface as a distinct typed error (NotSymmetric,NotPositiveSemidefinite,NotPositiveDefinite), never a silently repaired weight. -
Reuse the deterministic eigensolver. The achieved closed-loop poles MUST come from the
lawsynth-koopmaneigensolver applied toA − B K, not a second hand-rolled solver, so the whole pipeline shares one audited decomposition, and MUST be reported in that solver's canonical order. -
Determinism. Polynomial expansion, controllability, Gaussian elimination (largest-magnitude pivot, lowest index on a tie), the Lyapunov solve, and the Kleinman iteration MUST all be deterministic. Identical inputs MUST produce a bit-identical result: identical
KandP(tof64bit patterns) and an identical achieved-pole set in identical order.
Public API
place_poles(&Matrix /*A*/, &Matrix /*b, n×1*/, &[Complex] /*desired*/)
-> Result<Gain, FeedbackError>
lqr(&Matrix /*A*/, &Matrix /*B*/, &Matrix /*Q*/, &Matrix /*R*/)
-> Result<Gain, FeedbackError>
Gain { k: Matrix, achieved_poles: Vec<Complex>, p: Option<Matrix> }
Gain::is_stable(margin) -> bool
Matrix and Complex are re-exported from lawsynth-koopman so a caller builds
(A, B) and reads achieved poles without a separate dependency. Pole placement
returns p: None (it forms no value function); LQR returns p: Some(P). This
crate delivers the linear feedback-design library only; wiring it into a
controller, a discovery report, or a simulation loop is downstream and out of
scope here.
Honest scope & limits
- Pole placement is single-input only. Ackermann's formula applies to one
actuator (
bof width 1). Multi-input placement has extra freedom that must be resolved by a robustness criterion (Kautsky–Nichols / robust eigenstructure assignment); that is deliberately not implemented here, and a widerBis rejected rather than silently reduced. - LQR assumes stabilizability and
R ≻ 0. The Kleinman iteration needs an initial stabilizing gain; the Bass bootstrap constructs one for a controllable (hence stabilizable) pair, but a genuinely non-stabilizable pair — an unstable mode with no actuation — has no solution and is reported as such.Rmust be positive definite forR⁻¹to exist. - The gain is only as local as the linearization.
Ais a Jacobian at a point; the closed-loop guarantee is local. Nothing here certifies a region of attraction or behaviour away from the fixed point. - Numerical conditioning degrades near the edges. For large
n, a near-uncontrollable pair, or a fast desired spectrum, the controllability matrix, the matrix polynomial, and then² × n²Lyapunov system become ill-conditioned; the achieved poles then drift from the requested ones, which is precisely why the achieved spectrum is reported rather than assumed. A Riccati residual is likewise a modelling check, not a proof of optimality to machine precision. - Continuous-time only. The CARE and the
Re(λ) < 0stability notion are continuous-time; discrete-time placement / DARE are not covered.
Non-goals
- No multi-input / robust pole placement, no output feedback, no observer or Kalman-filter design (the separation principle is out of scope).
- No discrete-time design (DARE, deadbeat), no finite-horizon / time-varying LQR,
no
H∞or robust-control synthesis. - No region-of-attraction estimate, Lyapunov-function search, or any nonlinear or global stability guarantee for the underlying field.