Batch 9 of expansion-v2. Makes the analysis layer user-reachable, adds two
model-use capabilities, and threads an analysis job through the hosted platform.
Deterministic/offline/std-only.
crates/lawsynth-mpc (new): successive-linearization LQR-MPC. Relinearizes each
step (analytic A=∂f/∂x, B=∂f/∂u), solves a local LQR (lawsynth-feedback),
applies the first clamped move, advances the nonlinear plant by RK4. Regulates a
forced pendulum to <1e-3, respects saturation, stabilizes a Van der Pol limit
cycle; per-step gain bit-identical to direct LQR on a linear plant. Honest that
it's LQR-MPC, not constrained QP-MPC. 18 tests.
crates/lawsynth-propagate (new): coefficient→forecast uncertainty. Delta method
Cov(x(t))≈S·Cov(θ)·Sᵀ via forward sensitivities, plus seeded Monte-Carlo over the
bootstrap ensemble. Delta matches the (t·x0·e^-θt)²·s² closed form to <1e-9;
delta≈MC at small σ and honestly diverges (asymmetric MC band) at large σ.
covariance_from_ensemble closes the bootstrap→bands pipeline. 34 tests.
crates/lawsynth-cli: new analysis subcommands bifurcation/sensitivity/estimate/
reduce (shared linearize-at-fixed-point helper derives A/C/B from a world), with
honest guardrails (bifurcation needs a parameterized law; reduce needs a Hurwitz
point; estimate pole placement is single-output). 115 lib + 7 integration tests.
services/worker + scheduler: Job::AnalyzeStability + JobOutput::Stability threaded
through every worker match site (job/execute/artifacts/errors/http_error) and
proven first-class in the scheduler via an end-to-end submit→lease→execute test.
Gateway HTTP→Job decode noted as an honest follow-up. Worker 64 + scheduler tests.
specs/{model-predictive-control,forecast-uncertainty}: boundary specs.
Model-predictive-control boundary (v2-A)
This directory specifies deterministic successive-linearization model-
predictive control (MPC) — given a discovered nonlinear model ẋ = f(x, u),
driving the state to a setpoint by repeatedly linearizing about the current
operating point, designing a local LQR feedback, applying the first control
move, and advancing the true nonlinear plant one step. It is implemented in
crates/lawsynth-mpc. It is a boundary specification in the house style: it
states what a conforming implementation MUST do, and — crucially — what the
resulting controller is and is not allowed to claim.
Motivation
A discovered dynamical law with actuation is a controlled vector field
ẋ = f(x, u), where the state fields are symbolic Expr trees over the state
symbols and one or more control symbols. The engineering question is: choose a
control policy u(x) that drives the state to a target x_ref and holds it
there. The classical linear answer — LQR (crates/lawsynth-feedback) — applies
only to a linear pair (A, B); the field here is nonlinear.
Successive-linearization MPC bridges the two. At each control step, with the
current state x, it linearizes the nonlinear field about the operating point
(x, u_ref),
A = ∂f/∂x |(x, u_ref) B = ∂f/∂u |(x, u_ref),
designs an infinite-horizon LQR gain K for that local (A, B), applies the
first move u = u_ref − K (x − x_ref) (saturated to actuator limits), advances
the true nonlinear plant one fixed step, and re-linearizes at the new state.
This is the receding-horizon idea with the horizon subproblem solved by a local
LQR rather than a full trajectory optimization — equivalently, a gain-
scheduled LQR whose schedule is generated on the fly by the analytic Jacobian.
A is the same object crates/lawsynth-jacobian produces (analytic, exact
symbolic differentiation); B is the analogous partial ∂f/∂u, one column per
control symbol. The local design reuses the deterministic Kleinman LQR of
crates/lawsynth-feedback verbatim. LawSynth is deterministic and offline,
so identical inputs MUST yield a bit-identical trajectory.
What the controller IS
The returned trajectory is a property of the supplied field, the weights, the initial condition, and the step size — not of any data or of a global guarantee. The contract is:
- A closed loop of local designs, not a global optimum. At each step the applied gain is the exact LQR gain of the local linearization. The controller makes no claim of global optimality, of a horizon cost minimum, or of the constrained optimum when saturation is active.
- The plant advanced is the true nonlinear field. Linearization is used
only to compute the feedback gain; the state is advanced by RK4 on
f(x, u)itself, so the recorded trajectory is the genuine nonlinear closed-loop response, not a linear prediction. - Exactness where the model is linear. If
fis affine inxandu, the linearization is exact and constant, so every step designs the same gain, bit-identical to a directlqr(A, B, Q, R)solve, and the closed loop matches an LQR-controlled linear rollout. This is the conformance anchor. - Saturation by clamping, honestly labelled. When
[u_min, u_max]are given, each applied move is clamped element-wise. Clamping is not the constraint-optimal projection a QP-MPC would compute; it is a simple, honest actuator model that keeps every applieduwithin bounds. - A property of the expression, not of any fit. The controller carries no discovery confidence or fit residual. Those are separate, upstream concerns.
Requirements
-
Relinearize every step from the analytic model. At each control step an implementation MUST form
A = ∂f/∂xfrom the analytic Jacobian (analytic_jacobian) andB = ∂f/∂uby symbolically differentiating each field with respect to each control symbol (differentiate), and MUST evaluate both at the current(x, u_ref). The symbolic differentiation MAY be done once at construction and only evaluated per step; it MUST NOT be replaced by a finite-difference approximation. -
Design the local gain with the shared LQR. The per-step gain MUST come from
lawsynth-feedback::lqrapplied to the local(A, B, Q, R), so the whole pipeline shares one audited Riccati/Kleinman solve. A design failure (e.g.Rnot positive definite, an unstabilizable linearization, non- convergence) MUST surface as a distinct typed error, never a fabricated gain. -
Apply the first move with the stated law. The applied control MUST be
u = u_ref − K (x − x_ref), then clamped element-wise to[u_min, u_max]when those bounds are supplied.u_refdefaults to zero. -
Advance the true nonlinear plant by fixed-step RK4. The state MUST be advanced one step of size
dtby the classical four-stage Runge–Kutta method applied to the nonlinear fieldf(x, u)with the applieduheld constant across the four stages. No linear surrogate may be substituted for the plant step. -
Validate the problem at the boundary. Dimensions (
x₀,x_reflengthn;u_ref, saturation bounds lengthm;Qshapen×n;Rshapem×m), finiteness of all configuration values, a strictly positive finitedt, a non-zero horizon, a non-empty state and control set, every state having a field, andu_min ≤ u_maxper channel MUST each be checked, and a violation MUST surface as a distinct typed error before any integration runs. -
Reuse, do not re-derive. Linearization, LQR, and evaluation MUST reuse the
lawsynth-jacobian,lawsynth-feedback, andlawsynth-exprimplementations. No second Jacobian, Riccati solver, or expression evaluator may be hand-rolled here. -
Determinism. The symbolic Jacobian and control partials, their numeric evaluation, the Kleinman LQR iteration, the saturation clamp, and the RK4 advance MUST all be deterministic — no RNG, no clock, fixed loop order. Identical inputs MUST produce a bit-identical trajectory: identical state and control sequences to
f64bit patterns.
Public API
mpc_control(
fields: &[(Identifier, Expr)], // ẋ_i = f_i(x, u), matched to states
states: &[Identifier], // state ordering, length n
controls: &[Identifier], // control ordering, length m
config: &MpcConfig,
) -> Result<MpcTrajectory, MpcError>
MpcConfig {
initial_state, setpoint, // x₀, x_ref (length n)
control_reference, // u_ref (length m, default 0)
state_weight, control_weight, // Q (n×n), R (m×m)
dt, steps, // fixed step, horizon length
control_min, control_max, // optional saturation (length m)
}
MpcConfig::new(x0, x_ref, Q, R, dt, steps) // u_ref = 0, unsaturated
::with_control_reference(u_ref) / ::with_saturation(u_min, u_max)
MpcTrajectory::states() / controls() / gains() / times()
::final_state() / error_norm(k, x_ref) / final_error_norm(x_ref)
::bit_fingerprint() // raw f64 bits, for determinism checks
Matrix is re-exported from lawsynth-koopman (through lawsynth-feedback) so a
caller builds Q/R and reads per-step gains without a separate dependency.
This crate delivers the controller only; discovering the field, choosing the
weights, and reporting results are upstream/downstream and out of scope here.
Honest scope & limits
- Successive-linearization LQR-MPC, not QP-MPC. There is no horizon cost optimization and no constrained quadratic program. Each step solves an infinite-horizon LQR for the local linearization and applies its first move. Saturation is handled by clamping, which is not constraint-optimal — a true constrained MPC would re-optimize subject to the bounds. When the actuator saturates, the clamped move is generally suboptimal.
- Local stability only; no feasibility or recursive-stability guarantee. The closed-loop guarantee is exactly LQR's local one, applied pointwise along the trajectory. There is no proof of convergence for arbitrary initial conditions, no region-of-attraction estimate, and no recursive-feasibility / terminal-set argument of the kind constrained MPC provides. A run may fail to reach the setpoint (or diverge) for a strongly nonlinear plant, a distant start, or an actuator too weak or too saturated.
- A stabilizable linearization is required every step. Each step needs
lqr(A, B, Q, R)to succeed:(A, B)must be stabilizable andR ≻ 0. If a linearization along the path is not stabilizable (e.g. the localBloses rank, an uncontrollable unstable mode), the step fails and the error is propagated — the controller does not silently substitute a fallback. - Fixed-step accuracy. The plant is advanced by fixed-step RK4; there is no
adaptive step control or error estimate. Too large a
dtdegrades the plant simulation and can destabilize the closed loop irrespective of the gain.dtis the discretization of the plant simulation, not a control-horizon length. - Setpoint consistency is the caller's responsibility. The law
u = u_ref − K (x − x_ref)regulates tox_refonly if(x_ref, u_ref)is (near) an equilibrium off— i.e.f(x_ref, u_ref) ≈ 0. For a setpoint that is not an equilibrium the state settles to a nearby offset, not exactlyx_ref; the crate does not solve for a feedforwardu_ref. - The gain is only as local as the linearization. As in
specs/control-design,Ais a Jacobian at a point and the design is local; nothing here certifies behaviour away from the current operating point. - Continuous-time model, single fixed weighting.
fis a continuous-time field andQ,Rare fixed across the run (no time-varying or terminal weighting). Discrete-time / DARE design is out of scope.
Non-goals
- No constrained QP-MPC, no finite-horizon trajectory optimization, no terminal cost / terminal constraint set, no move-blocking or input-rate constraints.
- No output feedback, observer, or state estimation (full state is assumed measured); the separation principle is out of scope.
- No robustness / tube MPC, no disturbance model, no offset-free tracking via integral augmentation or feedforward equilibrium solve.
- No adaptive or multiple-shooting integration, no region-of-attraction or Lyapunov certificate for the nonlinear closed loop.