causal-hybrid-control 0.2.0__tar.gz

causal_hybrid_control-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - name: Sync dependencies
+        run: uv sync --group dev
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format check
+        run: uv run ruff format --check .
+      - name: Type check
+        run: uv run ty check
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Sync dependencies
+        run: uv sync --group dev
+      - name: Tests
+        run: uv run pytest

causal_hybrid_control-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: release
+
+# Cut a release by pushing an annotated tag: `git tag -a v0.1.0 -m ... && git push origin v0.1.0`.
+# Publishing uses PyPI Trusted Publishing (OIDC) -- no stored token. One-time PyPI-side setup:
+# add this repo + the `release.yml` workflow + the `pypi` environment as a trusted publisher.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Check metadata
+        run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

causal_hybrid_control-0.2.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# uv / venv
+.venv/
+uv.lock.bak
+
+# tooling caches
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.ty_cache/
+
+# Rocq / Coq build artifacts
+*.vo
+*.vok
+*.vos
+*.glob
+.nra.cache
+.*.aux
+.lia.cache
+
+# JAX / experiment artifacts
+*.npz
+*.pkl
+outputs/
+wandb/
+
+# datasets (notebooks download to a local cache; never commit data)
+data/
+
+# editors / OS
+.vscode/
+.idea/
+.zed/
+.DS_Store
+.ipynb_checkpoints/
+.coq-native/

causal_hybrid_control-0.2.0/.python-version

@@ -0,0 +1 @@
+3.14

causal_hybrid_control-0.2.0/CHANGELOG.md

@@ -0,0 +1,211 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to adhere to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) once the API stabilises (pre-1.0 it may
+still change).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-07-29
+
+Work landed on `main` since `v0.1.0`. The theme is **guarantees**: most of it is a machine-checked
+result line at the causal↔control seam (Maxima derivation → Rocq proof → numeric certificate), with the
+matching runtime primitives shipped alongside. The proof scripts themselves are in `proofs/` and the
+symbolic derivations in `validation/`.
+
+### Added
+
+- **Sensitivity-aware control under hidden confounding** (`chc.sensitivity`, a facade over
+  `chc.regret` + `chc.uncertainty`). Bounded-density-ratio (marginal MSM) worst-case effect as a CVaR
+  mixture → pessimism-radius inflation (`confounding_robust_inflation`, `msm_worst_case_mean`,
+  `confounding_robust_radius`); the confounding regret floor is *second order* in the effect bias
+  (`confounding_robust_lq_regret`, plus a matrix Frobenius lift); a **minimax controller** whose gain
+  the radius shifts under asymmetric over/under-shoot loss (`confounding_robust_control`, sign
+  dichotomy, piecewise improvement gap); the radius inside the replanning tube
+  (`confounding_robust_closed_loop_bound`). Grounded on a synthetic observational confounded
+  marketplace, then lifted into a genuine receding-horizon **closed loop** on a confounded plant
+  (`confounding_robust_tracking_loop`, `confounding_robust_tracking_benchmark`).
+- **`ConfoundingRobustPenalty`** (`chc.uncertainty`) — a `PenaltyModel` carrying the sensitivity radius
+  into the general pessimistic-control stack (`radius·Σ‖u_t‖`, from the *transition*-error bound
+  `‖Δ_B·u_t‖ ≤ radius·‖u_t‖`; an identification-radius regulariser rather than a certified cost bound,
+  since the latter needs a cost-to-go Lipschitz multiplier `lam_unc` currently absorbs), and **`ConfoundingRobustTask`** (`chc.benchmark`), its leaderboard row: under a
+  *hidden* confounder no estimator can help, and the radius still cuts regret ~40% vs
+  certainty-equivalence with separated multi-seed CIs.
+- **Certified planning** (`chc.uncertainty`, `chc.residual`) — certified-Lipschitz rollout-error tubes
+  via discrete Grönwall feeding the pessimism radius, with time-varying tubes, constraint tightening,
+  a certified-safe horizon and a closed-loop (replanning) variant; **`ContractiveResidual`** with a
+  certified negative log-norm, which replaces the `e^{LT}` growth with a bounded radius; a
+  **port-Hamiltonian** residual with a machine-checked damping-injection Lyapunov certificate;
+  **`WassersteinPenalty`**, a W1-DRO distribution-shift margin.
+- **`NestedCVaRPenalty`** (`chc.uncertainty`) — a time-consistent aggregation of ensemble
+  disagreement in the same `PenaltyModel` slot. `EnsembleUncertainty` *sums* member variance along the
+  trajectory, so one very bad step averages away against many quiet ones; this replaces the sum with
+  `rho_t = c_t + CVaR_alpha[rho_{t+1}]`, and `static_penalty_trajectory` keeps the other adversary
+  (commit to one member for the whole horizon) so the two are comparable. `nested_risk_certificate`
+  checks the ordering that must hold — nested ≥ static ≥ risk-neutral, collapsing at `alpha = 1` — and
+  the gap is the price of time consistency, which is what a receding-horizon controller needs if it is
+  not to chase its own tail across re-solves. Scoped honestly: with the members re-evaluated
+  independently the recursion collapses to `Sum_t CVaR_alpha[c_t]`, a risk-averse *aggregation* rule
+  rather than a dynamic-programming solve of a nested-risk MDP.
+- **`chc.pathway`** — one `causal_pathway(target)` API over the temporal causal graph, with
+  Rocq-certified walk-sum / geometric-truncation / weakest-link structural laws.
+- **Marketplace layer** — `chc.matching` (Kantorovich OT dispatch with dual surge prices) and
+  `chc.marketplace` (offline causal control under equilibrium interference, where naive and MOPO-style
+  baselines go negative); influence-function standard errors and CIs on the cross-fit DML effect.
+- **Certified strategic layer** (`chc.games`) — `fixed_point`, a differentiable equilibrium solver that
+  iterates to a *relative* residual and returns an `EquilibriumSolution` carrying `residual` and
+  `converged`, with the backward pass as the implicit-function VJP (`jax.custom_vjp`, adjoint solved as
+  its own fixed point) rather than an unrolled loop; `congestion_contraction_modulus` /
+  `congestion_damping` / `congestion_contraction_certificate` to certify or refuse a configuration
+  before it runs (`spec(J) ⊆ [0, ½]` sharp ⟹ the uniform Jacobian bound is below 1 iff
+  `0 < d < 4/(2+κ)` — sharp over the class of congestion maps, sufficient for any one game — with
+  `d* = 4/(4+κ)` certifying every `κ`); `equilibrium_transfer_certificate`, which measures the equilibrium's
+  *local* conditioning — exactly 1 in the ambient norm uniformly in `κ` (attained only along the mass
+  direction that mass conservation never excites) and strictly below 1 on the fixed-mass tangent space
+  where displacements actually live — while the naive contraction constant `1/μ` is loose by up to
+  100×. So a `C/μ²` regret bound must not take its constant from *this* solver's contraction margin.
+- **`chc.barrier`** — the sensitivity radius spent on a *constraint* instead of on the objective:
+  the robust control-barrier margin guaranteed against every effect in the identified set
+  (`robust_barrier_margin`), its maximiser — exactly zero once the radius swallows the control
+  channel, which is optimal and not conservatism (`robust_safe_action`), the closed-form certified
+  action set and the least-restrictive filter that clips a nominal action into it
+  (`admissible_action_interval`, `robust_safety_filter`), the sharp radius at which certification
+  dies (`identification_radius_threshold`) and the sensitivity level it corresponds to
+  (`barrier_gamma_star`) — *the largest sensitivity-model level under which the barrier stays
+  certified* (a model parameter, not a measured amount of hidden confounding). Both
+  thresholds are **case-split** rather than one formula: a self-satisfying drift gives `inf`, a
+  deficit beyond what a perfectly identified channel delivers gives an empty set, and `Δ(Γ)`
+  saturating at the CVaR gap gives `Γ* = inf`. The measured consequence: safety margin degrades at
+  **first** order in the effect bias — until the radius swallows the channel, past which the loss
+  saturates at `U·|g|` — while performance regret degrades at second, because the envelope theorem
+  protects an interior optimum and not a binding constraint. `safety_filter_benchmark` pays that argument in a closed loop on an
+  unstable plant whose reference sits past the limit: the radius spent on the constraint never
+  leaves the safe set, the same-sized budget spent the regret way violates on 93% of steps.
+  Re-exported through `chc.sensitivity`.
+- **`chc.plan.causal_plan`** — the one-call spine: a `CausalPlan` carrying the actions *together with*
+  the certified error tube and the `certified_actions` prefix, so a caller cannot take the plan and
+  leave the certificate behind. With no safety arguments it is exactly `projected_gradient_control`;
+  each safety argument switches on one existing layer, and an uncertainty penalty without a support
+  model is rejected rather than silently ignored.
+- **`chc.plan.certify_safety`** — the other half of the spine: §40 evaluated along a finished plan, so
+  the safety result has a consumer instead of staying an orphan primitive. Returns the certified
+  *prefix* (does the action the planner chose still clear the barrier at this `Γ`?) next to the plan's
+  `Γ*` (could **any** admissible action have, and up to which level?) — two questions that come apart
+  in both directions and are diagnostic together. The plan-level `Γ*` is the minimum over steps and is
+  *attained*: `Δ(Γ)` is increasing, so each step certifies on a down-set and the plan certifies on
+  their intersection; a step that certifies at no `Γ` empties it and reports `nan` rather than being
+  skipped. A separate call on a finished plan rather than a planner argument — it audits, it does not
+  silently change the actions. Re-exported through `chc.sensitivity`.
+- **`chc.spine`** (`scripts/spine_demo.py`) — the four layers on one decision, because until now every
+  layer had its own demo and none of them ran end to end. Two zones of a mobile driver pool, one
+  incentive lever whose `[+b, -b]` column *is* driver conservation, and a supply floor in the zone the
+  lever drains: an effect fitted from confounded logs (naively and with the backdoor adjustment), a
+  constrained plan with its Grönwall tube, a `certify_safety` audit of that plan, and finally the same
+  plan executed on the **true** plant so the offline numbers can be checked against what happened. The
+  confounded arm plans a cost of 13.6 and pays 38.5; `Γ*` separates the two arms *before either acts*
+  (7.46 vs 1.18) with no access to ground truth. Deliberately control-affine — `certify_safety` reads
+  the channel off the Jacobian at `u = 0`, which is exact for an affine plant and only a linearisation
+  otherwise, so the softmax-equilibrium market of `chc.marketplace` is the wrong plant to certify.
+- **`chc.reachability`** — a Hamilton–Jacobi backward reachable tube whose adversary is the §32
+  identification radius: `V(x,T) = max_u min_{ΔB} min_s h(ξ(s))` by Lax–Friedrichs on a 2-D grid, with
+  the same robust-margin algebra as `chc.barrier` but `p = ∇V` solved for rather than assumed. It
+  exists to price the barrier certificate, and `barrier_reachability_gap` is that price:
+  `valid_cbf` makes the CBF theorem executable (condition on all of `{h ≥ 0}` ⟹ the tube **is**
+  `{h ≥ 0}`, checked to a cell), and `certified_but_unreachable` measures where the *pointwise* §40
+  check certifies a state no controller can hold — on a relative-degree-2 barrier the §40 verdict is
+  identical at every radius while the true tube shrinks. Verified against two analytic solutions (a
+  rigidly sliding level set to `1e-5`; the double-integrator braking parabola to 100% off-boundary
+  agreement), with a CFL guard that refuses rather than reporting an optimistic safe set.
+- **Regret / guarantee line** — the orthogonal-to-control transfer theorem (order `p` → `2p`, scalar
+  and multivariate-LQ), multi-channel network control (debias *every* channel), the adaptive
+  information-exploration duality with its `√T` lower bound, the C2 end-to-end theorem with a clustered
+  van-Trees lower bound and an exposure-map generalisation, plus a batch of scoped propositions and
+  corollaries (doubly-robust control, H∞-as-pessimism, constrained piecewise-quadratic regret,
+  confounded turnpike, transportability, ensemble heterogeneity, partial-identification sign threshold).
+
+### Changed
+
+- Eleven rounds of external review folded in as **scope and honesty corrections**, not new claims: the
+  explicit-Euler contraction factor was wrong (`√(1+2μΔt+L²Δt²)`, sufficient step `Δt < 2c/L²`); the
+  confounding effect error needed the control magnitude to be dimensionally right; the `§35`
+  improvement gap is piecewise (the undershoot-dominant branch was unproved while the benchmark ran in
+  it); `§32` is the bounded-density-ratio *marginal* special case of Tan's MSM, not the full model, and
+  its monotonicity argument is feasible-set nesting; the confounded-marketplace benchmark is
+  *observational*, not a randomised switchback. Several results were relabelled to their honest status
+  (order-transfer *lemma*, local-not-global, scalar-not-universal, `≈`-not-`=`). Round eleven: the
+  equilibrium conditioning of `1` is an *ambient*-norm statement saturated by the mass-conservation
+  direction, and the binding number on the fixed-mass tangent space is strictly smaller; the safety
+  margin loss is `U·min(d,|g|)` and so first-order only while control authority lasts; the zero-action
+  rule in general reads "the identified interval contains zero", the symmetric ball being one case;
+  and the `§38` premium is quoted with both normalisations because they differ by an order of
+  magnitude.
+- Documentation counts corrected after an audit found a silently drifting entry count in the research
+  log; the README test count was stale by two releases.
+
+### Fixed
+
+- `ConfoundingRobustPenalty` used `‖u‖`, whose gradient is NaN at `u = 0` — exactly where the solver
+  starts — so `0·NaN` poisoned every step and the control stayed pinned at zero. Now a smoothed
+  `√(‖u‖²+ε)`, which zeroes the gradient at the origin and preserves the linear bound.
+- The congestion equilibrium ran a fixed trip count and returned whatever point it reached. Outside
+  the contraction region that is a 2-cycle, not an equilibrium: at `βc = 200` it returned a point with
+  residual 3.21 on a mass of 6.0 and most of the mass on the *least* attractive zone, and no caller
+  could tell. The solver now reports convergence; the root cause was the hard-coded damping `d = ½`,
+  whose ceiling is `βc < 6`, so `congestion_damping` supplies the modulus-optimal `d*` that contracts
+  for every `βc`. Both shipped users (`chc.marketplace`, causaldyn-bench Track H) sit at `βc = 5`,
+  inside the certified region, and their docstrings now say so executably.
+- The convergence tolerance was absolute while the residual carries the units of the state, so a
+  float32 solve at the shipped mass could not reach `1e-8` and reported failure at a residual of
+  3.8e-07. The residual is now relative (`‖x−T(x)‖ / max(1, ‖x‖)`).
+
+### Notes
+
+The repository moved to the `causaldyn` organisation and is public as of this release; all project
+URLs point there. This is the **first version published to PyPI** — `0.1.0` below was prepared and
+tagged locally, then overtaken by 71 commits before it was ever pushed, so it never reached an index.
+
+## [0.1.0] — 2026-07-19
+
+Prepared but never published; superseded by `0.2.0`. `chc` is a small JAX library that fuses
+**physics-structured hybrid dynamics**, **causal identification**, and **constrained optimal control**,
+made safe on offline/confounded data by an explicit **pessimism/support** layer — evaluating decisions
+as interventions, not correlations.
+
+### Added
+
+- **Hybrid dynamics & sensitivity** — additive `f_known + r_θ` (`chc.dynamics`); MLP / RBF-KAN / graph /
+  zero residual backends (`chc.residual`); RK4 rollout (`chc.integrate`); a hand-written discrete adjoint
+  verified against autodiff and finite differences, plus an adaptive `diffrax` continuous adjoint
+  (`chc.adjoint`); Lie–Trotter / Strang–Marchuk operator splitting (`chc.splitting`).
+- **Causal frontier** — pluggable effect estimators (backdoor OLS, IV/2SLS, cross-fitted Double ML,
+  sensitivity + refutation, VanderWeele–Ding **E-values**) behind one Strategy interface
+  (`chc.causal`, `chc.estimators`), with lazy EconML/DoWhy adapters; the **R-learner** CATE meta-learner;
+  staggered-adoption **DiD** — Callaway–Sant'Anna group-time ATT and the de Chaisemartin–d'Haultfoeuille
+  DID_M (`chc.did`); **augmented synthetic control** (`chc.scm`); Robins **g-methods** for time-varying
+  treatment (`chc.gmethods`); autocorrelation-robust CI testing + lagged-parent **discovery**
+  (`chc.independence`, `chc.discovery`); network/interference-aware DML with a learned GNN nuisance
+  (`chc.network_causal`).
+- **Offline safety & guarantees** — density-distance support penalty (`chc.support`) plus **calibrated**
+  deep-ensemble + split-conformal uncertainty (`chc.uncertainty`); IPS/SNIPS off-policy value + overlap
+  gate (`chc.offpolicy`); an **LQ certainty-equivalence regret bound** and a local nonlinear certificate
+  via linearisation (`chc.regret`, `chc.lqr.linearized_regret_certificate`).
+- **Control** — projected-gradient optimal control and receding-horizon MPC (`chc.control`, `chc.mpc`);
+  LQR / Riccati (`chc.lqr`); Koopman-LQR (`chc.koopman`); mean-field control (`chc.meanfield`); optimal
+  transport (`chc.transport`); differentiable Stackelberg games (`chc.games`); PMP time-optimal bang-bang
+  (`chc.mintime`); classical step-response metrics (`chc.metrics`).
+- **Structured operators & dynamic effects** — Toeplitz FFT matvec, Levinson–Durbin, Gohberg–Semencul
+  inverse + few-sample covariance (`chc.toeplitz`); impulse-response / local-projection dynamic effects
+  (`chc.irf`); Galerkin FEM and a mesh-free Deep Galerkin Poisson solver (`chc.galerkin`,
+  `chc.deep_galerkin`).
+- **Benchmark & real-data validation** — oracle-regret tasks (pricing, inventory, support-shift,
+  model-uncertainty) with a leaderboard and multi-seed bootstrap CIs (`chc.benchmark`); a causal-methods
+  leaderboard vs naive baselines (`chc.causal_bench`); the **LaLonde-Dehejia-Wahba** external causal
+  benchmark (`chc.lalonde`, recovers the randomised ATE from CPS-confounded data). The control loop is
+  validated live on a real **BOPTEST** `bestest_hydronic_heat_pump` emulator (via the `causaldyn-bench`
+  sibling), where the identification + forecast-MPC beat the tuned built-in baseline on every KPI.
+- **Tooling** — `src`-layout, `uv`-managed, `py.typed`; `ruff` + astral `ty` gates; CI test matrix on
+  Python 3.12 / 3.13 / 3.14.
+
+[0.2.0]: https://github.com/causaldyn/causal-hybrid-control/releases/tag/v0.2.0
+[0.1.0]: https://github.com/causaldyn/causal-hybrid-control/releases/tag/v0.1.0

causal_hybrid_control-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilia Gradina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

causal_hybrid_control-0.2.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: causal-hybrid-control
+Version: 0.2.0
+Summary: Physics-structured dynamics with a learned causal residual, controlled by constrained optimal control / MPC.
+Project-URL: Homepage, https://github.com/causaldyn/causal-hybrid-control
+Project-URL: Repository, https://github.com/causaldyn/causal-hybrid-control
+Project-URL: Issues, https://github.com/causaldyn/causal-hybrid-control/issues
+Project-URL: Changelog, https://github.com/causaldyn/causal-hybrid-control/blob/main/CHANGELOG.md
+Author-email: Ilia Gradina <ilia.gradina@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: causal-inference,hybrid-models,jax,mpc,optimal-control,scientific-machine-learning,system-identification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.12
+Requires-Dist: diffrax>=0.6
+Requires-Dist: equinox>=0.11.4
+Requires-Dist: jax>=0.4.30
+Requires-Dist: numpy>=1.26
+Requires-Dist: optax>=0.2.3
+Requires-Dist: scipy>=1.13
+Provides-Extra: trees
+Requires-Dist: catboost>=1.2; extra == 'trees'
+Requires-Dist: lightgbm>=4; extra == 'trees'
+Requires-Dist: scikit-learn>=1.4; extra == 'trees'
+Description-Content-Type: text/markdown
+
+# causal-hybrid-control
+
+Physics-structured dynamics with a **learned causal residual**, controlled by **constrained optimal
+control / MPC**, and made safe on offline, confounded data by an explicit **pessimism / support** layer.
+
+```
+ẋ = f_known(x, u, t; p) + r_θ(x, u, t)                         # known mechanism + learned residual
+u* = argmin_u  J_task(u) + λ_unc·U(x,u) + λ_supp·D((x,u), 𝒟)   # pessimistic constrained control
+```
+
+Most data science stops at prediction. The value is in *decisions* — and a decision changes the future,
+so it must be evaluated as an **intervention**, not a correlation, and chosen by **optimal control**, not
+by argmax over a predictive score. `chc` is a small JAX library for that step.
+
+## The one result
+
+On a confounded offline log, fitting the effect of the action *without* adjusting for the confounder
+flips its sign (true `+1.0` → naive `-0.2`). Control the true system with each estimate:
+
+```
+controller            cost      regret    viol     ood
+causal-CHC            4.59       -0.00    0.00    0.00
+oracle                4.59        0.00    0.00    0.00
+predictive        13740.08    13735.49    0.97    1.00
+```
+
+The **causal** controller matches the oracle; the **predictive** one is catastrophic on every metric —
+it drives the state the wrong way (`x → -20` for target `+2`), violates constraints 97% of the time, and
+acts entirely out of the logged support. That is one seed, with the constraint and support columns;
+`uv run python scripts/run_benchmark.py` runs this task and four others over 12 seeds with bootstrap
+CIs (predictive regret `13734.15 [13732.55, 13735.31]`), and
+`uv run --group viz python scripts/flagship_demo.py` draws the figure.
+
+## Install
+
+```bash
+uv sync            # JAX + Diffrax + Equinox + Optax + NumPy + SciPy (Python 3.12–3.14)
+uv run pytest      # 353 passed, 2 skipped (tigramite, lightgbm: bring-your-own-env)
+```
+
+## Quickstart
+
+```python
+import jax, jax.numpy as jnp
+from chc import DampedOscillator, HybridDynamics, KANResidual, QuadraticCost, mpc_control
+
+# hybrid dynamics: known oscillator + a learnable (KAN) residual, swappable for MLP/linear
+model = HybridDynamics(
+    known=DampedOscillator(omega=1.0, zeta=0.1),
+    residual=KANResidual(state_dim=2, control_dim=1, out_dim=2, key=jax.random.key(0)),
+)
+cost = QuadraticCost(Q=jnp.diag(jnp.array([1.0, 0.1])), R=jnp.array([[0.05]]),
+                     Qf=jnp.diag(jnp.array([5.0, 1.0])), x_target=jnp.zeros(2))
+
+xs, us = mpc_control(model, jnp.array([1.0, 0.0]), cost, dt=0.1,
+                     horizon=20, u_lo=-5.0, u_hi=5.0, n_steps=40)   # closed-loop MPC
+```
+
+## Example notebooks
+
+Worked, executed notebooks (figures + tables) under [`notebooks/`](notebooks/) — open in JupyterLab
+(`uv sync --group notebooks && uv run --group notebooks jupyter lab`) or read on GitHub:
+
+| notebook | what it shows |
+|---|---|
+| [`01_causal_vs_predictive_control`](notebooks/01_causal_vs_predictive_control.ipynb) | the headline: predictive control diverges under confounding, causal control matches the oracle |
+| [`02_learn_hidden_physics`](notebooks/02_learn_hidden_physics.ipynb) | hybrid dynamics + system ID: recover an omitted cubic term; multi-step training cuts drift |
+| [`03_causal_inference_toolkit`](notebooks/03_causal_inference_toolkit.ipynb) | adjustment · IV/2SLS · Double ML · sensitivity · refutation, side by side |
+| [`04_epidemic_and_pessimism`](notebooks/04_epidemic_and_pessimism.ipynb) | flatten an epidemic curve under a capacity cap; pessimism vs a greedy controller |
+| [`05_benchmark_scoreboard`](notebooks/05_benchmark_scoreboard.ipynb) | the scoreboard: regret vs oracle across every task — CHC lands next to the oracle, the baseline blows up |
+| [`05_confounding_robust_control`](notebooks/05_confounding_robust_control.ipynb) | when **no adjustment set exists**: a sensitivity level `Γ` → identification radius → minimax action. Worst-case cost 1.23 → 0.35; 96% cheaper at realistic confounding, and the price is a 26%-of-the-CE-downside premium when there is none |
+| [`06_cruise_control_confounded`](notebooks/06_cruise_control_confounded.ipynb) | relatable end-to-end: adaptive cruise control from confounded fleet logs (Simpson's paradox → IV → control) |
+| [`07_real_data_lalonde`](notebooks/07_real_data_lalonde.ipynb) | **real data, experimental ground truth**: on LaLonde NSW the naive estimate flips sign (−$8.5k), Double ML recovers the randomised truth — +$1.6k against the experiment's +$1.8k, within $234 |
+
+Sources are paired `.py` (jupytext) next to each `.ipynb`.
+
+## What's inside
+
+| area | module | what it does |
+|---|---|---|
+| dynamics | `dynamics`, `residual`, `integrate` | hybrid `f_known + r_θ`; MLP / **RBF-KAN** / graph / **port-Hamiltonian** (passive, Lyapunov-stable) / **Lipschitz-certified** residuals; RK4 |
+| sensitivity | `adjoint` | discrete adjoint (verified == autodiff == finite differences) |
+| classical OC | `lqr` | LQR / AKOR (Riccati) — the `r_θ→0` limit and correctness baseline |
+| identification | `train`, `causal`, `estimators`, `gmethods` | system ID (one/multi-step); pluggable effect backend — adjustment, **IV/2SLS**, **DML**, sensitivity, refutation, + optional **EconML/DoWhy** adapters; Robins' **g-formula** (cross-fitted) for a treatment *sequence* under time-varying confounding |
+| control | `cost`, `control`, `mpc`, `splitting`, `plan` | Bolza objective; projected-gradient OC; receding-horizon MPC; **Strang–Marchuk** splitting; `causal_plan` — the one-call spine returning a plan *with* its uncertainty tube and certified horizon attached |
+| offline safety | `support`, `offpolicy`, `uncertainty` | pessimism penalty; IPS/SNIPS off-policy value + overlap gate; **calibrated** deep-ensemble + split-conformal uncertainty; a **time-consistent nested-CVaR** aggregation of that disagreement (the risk-neutral sum averages one very bad step away); **Wasserstein-1 DRO** distribution-shift margin; **certified rollout tubes** (Lipschitz / contractive-log-norm Grönwall bounds → time-varying uncertainty tube, safety-tightening, certified-safe horizon), **Rocq-proved** |
+| guarantee | `regret` | LQ certainty-equivalence bound — quadratic in model error (Dean–Mania–Tu–Recht–Matni); **interference-aware regret certificate** (extra exposure-map-error term), **machine-checked in Rocq** |
+| sensitivity-aware control | `sensitivity` (facade over `regret`, `uncertainty`, `barrier`) | **control under HIDDEN CONFOUNDING**: bounded-density-ratio (MSM) CVaR worst-case → pessimism-radius inflation; the confounding-regret floor is *second-order* in the effect bias; a **minimax controller** that shifts the gain under asymmetric (over/under-shoot) loss and beats certainty-equivalence — now a **closed-loop** controller on a confounded dynamic plant (bounds the worst-case downside, 82% cheaper over 30 steps), plus a `ConfoundingRobustPenalty` that carries the sensitivity radius into the general pessimistic-control stack — all **Rocq-certified**. `chc.sensitivity` is the one-import surface (estimate→radius→control) |
+| safety under partial ID | `barrier`, `plan` | the same sensitivity radius spent on a **constraint**: robust control-barrier margin, a least-restrictive safety filter (closed-form certified action interval, no QP), and `Gamma*` — **the largest sensitivity-model level under which the barrier stays certified** (a model parameter, not measured confounding). Safety degrades at *first* order in the effect bias (until the radius swallows the channel and the loss saturates) where performance regret degrades at second (the envelope theorem protects objectives, not binding constraints), **Rocq-certified**; in closed loop a regret-sized budget violates the limit on 93% of steps where the constraint-sized one never does. `certify_safety` audits a finished plan against all of it — the certified prefix next to the plan's `Gamma*` (the weakest step's, exactly) |
+| what the certificate is worth | `reachability` | the **Hamilton–Jacobi** answer the barrier only approximates: `V(x,T) = max_u min_{ΔB} min_s h(ξ(s))` on a Lax–Friedrichs grid, with the §32 identification radius as the adversary. Same robust-margin algebra as `barrier`, but `p = ∇V` is *solved for* rather than assumed. Turns the CBF theorem into an executable check (condition on all of `{h ≥ 0}` ⟹ the tube **is** `{h ≥ 0}`) and prices what pointwise certification misses — on a relative-degree-2 barrier the §40 verdict is identical at every radius while the true tube shrinks (6.4% of the grid certified-and-unreachable), so `certify_safety`'s per-step prefix is a filter, not a proof. `uv run python scripts/reachability_demo.py` |
+| end to end | `spine` | all four layers on **one** decision — confounded logs → causal gain → constrained plan → `Gamma*` certificate → the same plan run on the *true* plant. Two zones of a mobile driver pool, one incentive lever whose `[+b, -b]` column is driver conservation, a supply floor in the zone it drains. The confounded arm plans 13.6 and pays 38.5; `Gamma*` tells the two arms apart (7.46 vs 1.18) **before either acts**, without ground truth. `uv run python scripts/spine_demo.py` |
+| causal frontier | `did`, `scm`, `estimators`, `causal` | Callaway–Sant'Anna staggered **DiD**; **augmented synthetic control**; **R-learner** CATE; **E-values** beside Cinelli–Hazlett; **influence-function CIs** on cross-fit DML |
+| dynamic effects | `irf`, `toeplitz` | impulse-response / local-projection dynamic effects; Toeplitz / Levinson–Durbin / Gohberg–Semencul operators |
+| structure discovery | `discovery`, `independence`, `network_causal`, `pathway` | lagged-parent discovery; MCI partial-correlation test; network/spillover orthogonal DML; **ranked temporal causal pathway** — which lagged variables & multi-step chains drive a target, signed + actionable (Rocq-certified walk-sum / geometric-truncation / weakest-link laws) |
+| advanced control | `koopman`, `meanfield`, `transport`, `matching`, `games`, `mintime` | Koopman-LQR; mean-field control; continuum + discrete **Kantorovich OT** (driver↔rider matching → **dual surge prices**); differentiable Stackelberg games over a **certified** congestion equilibrium (implicit-function gradients, contraction certificate, optimal damping — the solver reports its residual instead of silently returning a non-equilibrium); PMP time-optimal bang-bang |
+| marketplace moat | `marketplace` | **offline causal control under equilibrium interference**: learn incentives from confounded switchback logs where SUTVA fails — de-confounded + equilibrium-aware + W-DRO-pessimistic control recovers the oracle where MOPO / naive-causal go *negative* |
+| evaluation | `benchmark`, `causal_bench`, `flagship`, `lalonde`, `metrics`, `surrogate` | pricing / inventory / support-shift / **model-uncertainty** / **confounding-robust** oracle-regret tasks + leaderboard with multi-seed bootstrap CIs; a causal-methods table scoring every frontier estimator against the naive baseline it is meant to beat; real-data **LaLonde** validation; step-response quality metrics; a gradient-boosted tree surrogate as the tabular prediction competitor (optional `trees` extra) |
+| scientific / PDE | `epidemic`, `galerkin`, `deep_galerkin` | SIR epidemic control (flatten the curve); 1D/2D Galerkin FEM (progonka); mesh-free **Deep Galerkin** neural Poisson solver |
+
+## Validation
+
+Correctness is cross-checked in independent tools, symbolic first (`validation/`): the ARE / matrix
+exponential are verified **Maxima**-authoritative (exact + high-precision `bfloat`) against **PARI/GP**
+(50-digit) and **Octave**, with SciPy used only as the fast float64 numeric. The control and guarantee
+invariants are **formally proved in Rocq** — 37 files under `proofs/`, from the box-projection bounds
+and idempotence (`box_projection.v`) to the interference-aware regret certificate.
+
+## Honest positioning
+
+`chc` composes ideas that exist — hybrid dynamics (SciML UDE), pessimistic offline control
+(MOPO/MOReL/Delphic), sequential causal identification (g-methods / dynamic treatment regimes),
+differentiable control (Neuromancer). The contribution is the *integration behind one API* plus a
+benchmark with ground-truth interventional effects. KAN is **one interpretable residual backend**, not
+the identity of the framework. The release-by-release record, scope corrections included, is in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+## Status
+
+Early (`v0.2.0`), single-author, research code (354 collected tests; Python 3.12–3.14, astral `ruff` + `ty`).
+Working: hybrid dynamics + adjoint (discrete and adaptive `diffrax`), LQR, system ID (one-/multi-step),
+causal identification (adjustment / IV / DML / sensitivity / refutation) plus the modern frontier —
+Callaway–Sant'Anna staggered DiD, augmented synthetic control, R-learner CATE, E-values; **calibrated**
+pessimism (deep ensemble + split conformal) and an LQ certainty-equivalence regret guarantee; MPC,
+Strang–Marchuk splitting, off-policy gate, KAN/MLP/Graph residual backends; advanced control backends
+(Koopman-LQR, mean-field, optimal transport, differentiable Stackelberg games, PMP time-optimal
+bang-bang); dynamic-effect IRFs + structured Toeplitz/Levinson/Gohberg–Semencul operators; lagged
+structure discovery; five benchmark tasks (pricing, inventory, support-shift, model-uncertainty,
+confounding-robust) with multi-seed bootstrap CIs; two flagships (pricing, epidemic); 1D/2D Galerkin FEM + a mesh-free Deep
+Galerkin neural Poisson solver; and step-response quality metrics. Both halves are now validated on
+**real** targets, not just synthetic ones: the **causal identification core** on real data with an
+experimental ground truth (notebook 07, LaLonde NSW: the naive estimate flips sign, Double ML recovers
+the randomised benchmark), and the **control loop** on a real building emulator — the identification +
+forecast-MPC of this library, run via `causaldyn-bench` against a live **BOPTEST**
+`bestest_hydronic_heat_pump`, beats the tuned built-in baseline on *every* KPI at once (thermal
+discomfort 8.01→7.32, energy 0.393→0.354, cost 0.100→0.090, emissions 0.066→0.059 — a clean Pareto
+win). Roadmap: more real tasks, the Medium/paper writeups, and — only if a real-time/edge deployment
+target appears — a compiled runtime.
+
+## License
+
+MIT