PyDiffGame 2.0.3__tar.gz → 2.0.4__tar.gz

{pydiffgame-2.0.3 → pydiffgame-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyDiffGame
-Version: 2.0.3
+Version: 2.0.4
 Summary: Nash-equilibrium solutions to linear-quadratic differential games, via a reduction of the Game Hamilton-Jacobi-Bellman equations to coupled algebraic and differential Riccati equations for multi-objective dynamical control systems.
 Project-URL: Homepage, https://krichelj.github.io/PyDiffGame/
 Project-URL: Repository, https://github.com/krichelj/PyDiffGame
@@ -58,7 +58,7 @@ Requires-Dist: control>=0.10; extra == 'examples'
 Description-Content-Type: text/markdown
 
 <p align="center">
-    <img alt="PyDiffGame logo" src="https://raw.githubusercontent.com/krichelj/PyDiffGame/master/images/logo.png" width="420"/>
+    <img alt="PyDiffGame logo" src="https://raw.githubusercontent.com/krichelj/PyDiffGame/master/images/logo.gif" width="420"/>
 </p>
 
 <p align="center">
@@ -83,7 +83,8 @@ Description-Content-Type: text/markdown
 * [Quick start](#quick-start)
 * [Input parameters](#input-parameters)
 * [Tutorial: masses on springs](#tutorial-masses-on-springs)
-* [More examples](#more-examples)
+* [Robust control: H∞ as a game](#robust-control-h-as-a-game)
+* [Examples — a walkthrough](#examples--a-walkthrough)
 * [Testing and development](#testing-and-development)
 * [Citing](#citing)
 * [Acknowledgments](#acknowledgments)
@@ -332,17 +333,73 @@ player, without re-tuning one monolithic cost matrix.
 > [`tools/generate_readme_figures.py`](https://github.com/krichelj/PyDiffGame/blob/master/tools/generate_readme_figures.py)
 > (`uv run python tools/generate_readme_figures.py`), so they always match the current code.
 
-# More examples
+# Robust control: H∞ as a game
 
-The [`src/PyDiffGame/examples`](https://github.com/krichelj/PyDiffGame/tree/master/src/PyDiffGame/examples)
-directory contains further worked comparisons:
+A game ties the centralized LQR on a shared cost — it cannot beat it. The place a
+differential game **provably wins** is *robustness*: classical **H∞** state feedback **is**
+the saddle point of a two-player zero-sum game in which the controller minimises and an
+adversarial disturbance maximises. PyDiffGame ships it as `ContinuousHInfinityControl`,
+completing the family next to the LQR and the N-player Nash game:
 
-| Example | System |
-| --- | --- |
-| [`MassesWithSpringsComparison.py`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/MassesWithSpringsComparison.py) | Chain of masses coupled by springs (the tutorial above) |
-| [`InvertedPendulumComparison.py`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/InvertedPendulumComparison.py) | Inverted pendulum on a cart |
-| [`PVTOL.py`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/PVTOL.py) · [`PVTOLComparison.py`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/PVTOLComparison.py) | Planar vertical take-off & landing aircraft |
-| [`QuadRotorControl.py`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/QuadRotorControl.py) | Quadrotor attitude / position control |
+```python
+import numpy as np
+from PyDiffGame import ContinuousHInfinityControl
+
+A   = np.array([[0.0, 1.0], [0.0, 0.0]])   # a cart: position, velocity
+B   = np.array([[0.0], [1.0]])             # control force
+B_w = np.array([[0.0], [1.0]])             # disturbance force
+Q, R = np.diag([1.0, 0.0]), np.array([[1.0]])
+
+robust = ContinuousHInfinityControl(A, B, B_w, Q, R).solve()   # picks gamma = 1.3 * gamma*
+print(robust.K)                      # robust feedback gain, u = -K x
+print(robust.worst_case_gain()[0])   # closed-loop ||G_zw||inf — provably below the LQR's
+```
+
+It solves the **game** algebraic Riccati equation whose quadratic term
+`B R⁻¹ Bᵀ − γ⁻² B_w B_wᵀ` is *indefinite* — exactly what an ordinary LQR Riccati solver
+cannot do — via the Hamiltonian/Schur method, auto-finds the optimal robustness level
+`γ*`, and reports the formal worst-case L2 gain. Across a
+[13-system benchmark](https://github.com/krichelj/PyDiffGame/tree/master/benchmarks)
+(carts, vehicles, aircraft, drones, flexible structures) it reduces the worst-case
+disturbance gain on every system, **practically significantly on 10/13** — most where the
+LQR leaves a sharp resonant peak — each at a documented nominal-cost price:
+
+<p align="center">
+    <img alt="H-infinity game vs LQR under worst-case disturbance (inverted pendulum)" src="https://raw.githubusercontent.com/krichelj/PyDiffGame/bbd010f15ee13adc2bba5e7b99e1a3ecc0238583/benchmarks/results/robust_inverted_pendulum.gif" width="860"/>
+</p>
+
+Left: the pendulum-angle response to the worst-case disturbance (H∞ roughly halves
+it). Right: the `σmax(ω)` curves whose peak *is* the worst-case gain — the LQR's
+resonant peak (≈1.92) flattened by the H∞ game to ≈1.25. The
+[**robustness showcase**](https://github.com/krichelj/PyDiffGame/blob/master/benchmarks/README.md)
+animates every system.
+
+# Examples — a walkthrough
+
+The package ships four worked **LQR-vs-game comparisons** under
+[`src/PyDiffGame/examples`](https://github.com/krichelj/PyDiffGame/tree/master/src/PyDiffGame/examples);
+each builds a system, designs an LQR and a decomposed game on it, runs both and reports the
+costs. Run any of them with `uv run python -m PyDiffGame.examples.<name>`:
+
+| Example | System | What it shows |
+| --- | --- | --- |
+| [`MassesWithSpringsComparison`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/MassesWithSpringsComparison.py) | Chain of masses coupled by springs | The **lossless** modal decomposition (the tutorial above): the game reproduces the monolithic LQR optimum |
+| [`InvertedPendulumComparison`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/InvertedPendulumComparison.py) | Inverted pendulum on a cart | An **unstable, underactuated** plant; the nonlinear closed loop can be simulated from the designed gains |
+| [`PVTOLComparison`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/PVTOLComparison.py) · [`PVTOL`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/PVTOL.py) | Planar vertical take-off & landing aircraft | A 6-state aircraft with input decomposition across players |
+| [`QuadRotorControl`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/QuadRotorControl.py) | Quadrotor attitude / position control | A larger nonlinear vehicle with a cascaded design |
+
+For the **full study** — PyDiffGame vs [python-control](https://python-control.readthedocs.io/)
+across 13 systems on both the *nominal* cost (lossless tie / price of anarchy) and the
+*robustness* metric, with rendered GIFs, a metrics report and an adversarial review of the
+methodology — see
+[`benchmarks/`](https://github.com/krichelj/PyDiffGame/tree/master/benchmarks) and its
+[README](https://github.com/krichelj/PyDiffGame/blob/master/benchmarks/README.md):
+
+```bash
+uv run --extra dev python -m benchmarks.run_masses          # nominal: game == LQR (lossless)
+uv run --extra dev python -m benchmarks.run_anarchy         # nominal: the price of anarchy
+uv run --extra dev python -m benchmarks.run_robust_suite    # the 13-system robustness suite + report
+```
 
 # Testing and development
 

{pydiffgame-2.0.3 → pydiffgame-2.0.4}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-    <img alt="PyDiffGame logo" src="https://raw.githubusercontent.com/krichelj/PyDiffGame/master/images/logo.png" width="420"/>
+    <img alt="PyDiffGame logo" src="https://raw.githubusercontent.com/krichelj/PyDiffGame/master/images/logo.gif" width="420"/>
 </p>
 
 <p align="center">
@@ -24,7 +24,8 @@
 * [Quick start](#quick-start)
 * [Input parameters](#input-parameters)
 * [Tutorial: masses on springs](#tutorial-masses-on-springs)
-* [More examples](#more-examples)
+* [Robust control: H∞ as a game](#robust-control-h-as-a-game)
+* [Examples — a walkthrough](#examples--a-walkthrough)
 * [Testing and development](#testing-and-development)
 * [Citing](#citing)
 * [Acknowledgments](#acknowledgments)
@@ -273,17 +274,73 @@ player, without re-tuning one monolithic cost matrix.
 > [`tools/generate_readme_figures.py`](https://github.com/krichelj/PyDiffGame/blob/master/tools/generate_readme_figures.py)
 > (`uv run python tools/generate_readme_figures.py`), so they always match the current code.
 
-# More examples
+# Robust control: H∞ as a game
 
-The [`src/PyDiffGame/examples`](https://github.com/krichelj/PyDiffGame/tree/master/src/PyDiffGame/examples)
-directory contains further worked comparisons:
+A game ties the centralized LQR on a shared cost — it cannot beat it. The place a
+differential game **provably wins** is *robustness*: classical **H∞** state feedback **is**
+the saddle point of a two-player zero-sum game in which the controller minimises and an
+adversarial disturbance maximises. PyDiffGame ships it as `ContinuousHInfinityControl`,
+completing the family next to the LQR and the N-player Nash game:
 
-| Example | System |
-| --- | --- |
-| [`MassesWithSpringsComparison.py`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/MassesWithSpringsComparison.py) | Chain of masses coupled by springs (the tutorial above) |
-| [`InvertedPendulumComparison.py`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/InvertedPendulumComparison.py) | Inverted pendulum on a cart |
-| [`PVTOL.py`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/PVTOL.py) · [`PVTOLComparison.py`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/PVTOLComparison.py) | Planar vertical take-off & landing aircraft |
-| [`QuadRotorControl.py`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/QuadRotorControl.py) | Quadrotor attitude / position control |
+```python
+import numpy as np
+from PyDiffGame import ContinuousHInfinityControl
+
+A   = np.array([[0.0, 1.0], [0.0, 0.0]])   # a cart: position, velocity
+B   = np.array([[0.0], [1.0]])             # control force
+B_w = np.array([[0.0], [1.0]])             # disturbance force
+Q, R = np.diag([1.0, 0.0]), np.array([[1.0]])
+
+robust = ContinuousHInfinityControl(A, B, B_w, Q, R).solve()   # picks gamma = 1.3 * gamma*
+print(robust.K)                      # robust feedback gain, u = -K x
+print(robust.worst_case_gain()[0])   # closed-loop ||G_zw||inf — provably below the LQR's
+```
+
+It solves the **game** algebraic Riccati equation whose quadratic term
+`B R⁻¹ Bᵀ − γ⁻² B_w B_wᵀ` is *indefinite* — exactly what an ordinary LQR Riccati solver
+cannot do — via the Hamiltonian/Schur method, auto-finds the optimal robustness level
+`γ*`, and reports the formal worst-case L2 gain. Across a
+[13-system benchmark](https://github.com/krichelj/PyDiffGame/tree/master/benchmarks)
+(carts, vehicles, aircraft, drones, flexible structures) it reduces the worst-case
+disturbance gain on every system, **practically significantly on 10/13** — most where the
+LQR leaves a sharp resonant peak — each at a documented nominal-cost price:
+
+<p align="center">
+    <img alt="H-infinity game vs LQR under worst-case disturbance (inverted pendulum)" src="https://raw.githubusercontent.com/krichelj/PyDiffGame/bbd010f15ee13adc2bba5e7b99e1a3ecc0238583/benchmarks/results/robust_inverted_pendulum.gif" width="860"/>
+</p>
+
+Left: the pendulum-angle response to the worst-case disturbance (H∞ roughly halves
+it). Right: the `σmax(ω)` curves whose peak *is* the worst-case gain — the LQR's
+resonant peak (≈1.92) flattened by the H∞ game to ≈1.25. The
+[**robustness showcase**](https://github.com/krichelj/PyDiffGame/blob/master/benchmarks/README.md)
+animates every system.
+
+# Examples — a walkthrough
+
+The package ships four worked **LQR-vs-game comparisons** under
+[`src/PyDiffGame/examples`](https://github.com/krichelj/PyDiffGame/tree/master/src/PyDiffGame/examples);
+each builds a system, designs an LQR and a decomposed game on it, runs both and reports the
+costs. Run any of them with `uv run python -m PyDiffGame.examples.<name>`:
+
+| Example | System | What it shows |
+| --- | --- | --- |
+| [`MassesWithSpringsComparison`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/MassesWithSpringsComparison.py) | Chain of masses coupled by springs | The **lossless** modal decomposition (the tutorial above): the game reproduces the monolithic LQR optimum |
+| [`InvertedPendulumComparison`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/InvertedPendulumComparison.py) | Inverted pendulum on a cart | An **unstable, underactuated** plant; the nonlinear closed loop can be simulated from the designed gains |
+| [`PVTOLComparison`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/PVTOLComparison.py) · [`PVTOL`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/PVTOL.py) | Planar vertical take-off & landing aircraft | A 6-state aircraft with input decomposition across players |
+| [`QuadRotorControl`](https://github.com/krichelj/PyDiffGame/blob/master/src/PyDiffGame/examples/QuadRotorControl.py) | Quadrotor attitude / position control | A larger nonlinear vehicle with a cascaded design |
+
+For the **full study** — PyDiffGame vs [python-control](https://python-control.readthedocs.io/)
+across 13 systems on both the *nominal* cost (lossless tie / price of anarchy) and the
+*robustness* metric, with rendered GIFs, a metrics report and an adversarial review of the
+methodology — see
+[`benchmarks/`](https://github.com/krichelj/PyDiffGame/tree/master/benchmarks) and its
+[README](https://github.com/krichelj/PyDiffGame/blob/master/benchmarks/README.md):
+
+```bash
+uv run --extra dev python -m benchmarks.run_masses          # nominal: game == LQR (lossless)
+uv run --extra dev python -m benchmarks.run_anarchy         # nominal: the price of anarchy
+uv run --extra dev python -m benchmarks.run_robust_suite    # the 13-system robustness suite + report
+```
 
 # Testing and development
 

pydiffgame-2.0.4/benchmarks/README.md

@@ -0,0 +1,109 @@
+# PyDiffGame benchmark study — where a differential game actually helps
+
+This directory is an honest, reproducible head-to-head between **PyDiffGame** and
+the **[python-control](https://python-control.readthedocs.io/)** package across a
+catalogue of standard control systems (carts, vehicles, aircraft, drones and
+flexible structures), with rendered GIFs and a formal verification of *where*
+the differential-game approach beats classical optimal control — and where it
+honestly does not.
+
+## TL;DR (the honest scientific bottom line)
+
+1. **On a single shared quadratic cost, a differential game cannot beat a
+   centralized LQR — at best it ties it.** This is not a tuning failure, it is
+   theory: the centralized LQR is the optimum of that cost, and a Nash game is a
+   *constrained* (decomposed) design, so its cost is `>= LQR` (price of anarchy),
+   with equality when the decomposition is lossless. We verify the *lossless*
+   case directly: on the masses-on-springs system PyDiffGame's modal game
+   reproduces the python-control LQR **to ~5e-12 on every metric**, disturbances
+   included. No boost — and we say so.
+
+2. **The real, formally-verifiable win is robustness.** Robust (H-infinity)
+   control *is* a differential game — the saddle point of a controller-vs-
+   adversarial-disturbance zero-sum game. PyDiffGame now ships this as
+   `ContinuousHInfinityControl`, and it **provably reduces the worst-case
+   disturbance gain** an LQR leaves on the table — at a documented nominal-cost
+   price, and only when the plant has worst-case gain to recover.
+
+## What is measured
+
+For every system we design two state-feedback controllers on the **same**
+weights `(Q, R)`:
+
+| controller | what it optimizes |
+| --- | --- |
+| `control.lqr` (python-control) | nominal cost (no disturbance) |
+| `PyDiffGame.ContinuousHInfinityControl` | worst-case disturbance gain (the game) |
+
+and report, on the same closed loop:
+
+- **`‖G_zw‖∞`** — the closed-loop worst-case L2 gain from the disturbance to the
+  weighted performance output `z = [Q^{1/2}x; R^{1/2}u]` (the formal robustness
+  metric; lower is more robust). Computed slycot-free by a refined frequency
+  sweep.
+- **time-domain peak** of the output under the single worst-case sinusoidal
+  disturbance (at the LQR's most vulnerable frequency).
+- **nominal LQ cost penalty** — how much nominal performance the robust design
+  gives up (always `>= 0`, since the LQR is the nominal optimum; this is the
+  *price* of robustness, reported honestly alongside the gain).
+
+## Nominal regime (two honest outcomes)
+
+On the shared cost a game never beats the centralized LQR; it either ties it or
+pays a small price. Both happen, and both are shown:
+
+- **Lossless tie** — `run_masses.py`: with the *modal* decomposition the
+  objectives decouple, so PyDiffGame's Nash game reproduces the LQR to ~5e-12 on
+  every metric (`results/masses_pdg_vs_lqr.gif`).
+- **Price of anarchy** — `run_anarchy.py`: two carts with *competing*
+  per-cart objectives and one actuator each. The decentralized Nash equilibrium
+  costs **+0.33%** on the joint objective vs the centralized LQR — while using
+  *less* control energy and overshoot (`results/coupled_carts_anarchy.gif`). The
+  tiny price buys decentralization and compositionality.
+
+## Results (robustness)
+
+See [`results/ROBUSTNESS_REPORT.md`](results/ROBUSTNESS_REPORT.md) for the full
+auto-generated table, and `results/robust_<system>.gif` for each animation
+(left: time response to the worst-case disturbance; right: the `σmax(ω)` curves
+whose peak *is* `‖G_zw‖∞`).
+
+<p align="center">
+    <img alt="H-infinity game vs LQR under worst-case disturbance (inverted pendulum)" src="results/robust_inverted_pendulum.gif" width="820"/>
+</p>
+
+*Inverted pendulum: the LQR leaves a sharp resonant peak (`σmax ≈ 1.92`) that the
+H∞ game flattens to `≈ 1.25` (−35% worst-case gain), roughly halving the
+pendulum-angle response to the worst-case disturbance — at a documented nominal-cost
+price. The honest high-frequency trade-off (H∞ slightly higher past the peak) is
+visible too.*
+
+Headline (honest): all 13 systems show a *relative* worst-case-gain reduction,
+but only the ones with a **non-negligible absolute gain** matter in practice —
+**10/13 are practically significant** (inverted pendulum +35%, PVTOL/quadrotor
++26%, seismic building +24%, flexible two-mass / cart / DC motor ~+22%, gantry
+crane / active suspension / aircraft ~+15%, ...), exactly the lightly-damped and
+unstable plants where the LQR leaves a sharp resonant peak. The two cars
+(cruise, bicycle) have an absolute worst-case gain of ~0 — the disturbance is
+already rejected by *any* reasonable controller — so their real relative
+reductions are **not practically meaningful**, and we say so rather than headline
+a "10/10 win". (The bicycle's earlier apparent "tie" turned out to be a `γ*`
+numerical artifact, caught by the methodology review and fixed; the corrected
+result is a real-but-immaterial relative reduction.)
+
+## Reproduce
+
+```bash
+uv run --extra dev python -m benchmarks.run_masses          # nominal: game == LQR (lossless)
+uv run --extra dev python -m benchmarks.robust_compare      # one robust comparison + GIF
+uv run --extra dev python -m benchmarks.run_robust_suite    # the full 10-system suite + report
+```
+
+## Rigor
+
+The catalogue models were verified entry-for-entry against the controls /
+vehicle-dynamics / flight-dynamics literature, and the comparison methodology
+(GARE solve, `γ*` search, the worst-case-gain metric, the nominal-cost
+accounting, and the fairness of scoring both controllers on the same output) was
+adversarially reviewed; the review hardened PyDiffGame's `γ*` search against a
+boundary numerical instability (now regression-tested).