cranebench 0.1.2__tar.gz

cranebench-0.1.2/LICENSE.txt

@@ -0,0 +1,8 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, the cranebench authors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the conditions of the BSD 3-Clause
+License are met.

cranebench-0.1.2/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: cranebench
+Version: 0.1.2
+Summary: A reproducible benchmark for underactuated crane control
+Author: S. Podliesnyi, O. Sheremet, B. Vorobiov
+License-Expression: BSD-3-Clause
+Project-URL: Repository, https://github.com/spodlesny2318-arch/Cranebench
+Project-URL: Issues, https://github.com/spodlesny2318-arch/Cranebench/issues
+Keywords: crane,underactuated,benchmark,reproducibility,sliding mode control,Monte Carlo
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: matplotlib>=3.6; extra == "dev"
+Requires-Dist: sympy>=1.12; extra == "dev"
+Dynamic: license-file
+
+# cranebench
+
+
+A reproducible benchmark for the control of underactuated crane systems.
+
+Crane control papers are almost never comparable with one another. Each one
+defines its own plant, its own manoeuvre, its own wind, its own uncertainty
+range and its own metrics, and then reports that the proposed controller beats
+the baselines the authors implemented themselves. `cranebench` fixes the bench
+so that the controller becomes the only thing that varies.
+
+The package contains **no novel controller**. That is deliberate. Its content
+is the plants, the disturbance models, the paired uncertainty design, the frozen
+metric module, the provenance ledger and five classical baselines.
+
+## Install
+
+```bash
+python -m pip install ".[dev]"
+python -m pytest -q
+```
+
+These commands apply to the source checkout. The separately supplied article
+reproducibility bundle contains retained campaign data and the revision audit.
+Installing the library alone does not install those campaign archives.
+
+Requires Python >= 3.10, NumPy >= 1.24 and SciPy >= 1.10.
+
+The development build `0.1.2.dev0` was uploaded to TestPyPI and the wheel was
+installed from that test index in a clean environment. TestPyPI is separate from
+the production PyPI index. The versioned source distribution is published with the GitHub release, and that same release is archived on Zenodo. A package-name installation route is available from the production PyPI index after publication.
+Compatibility profiles and the GitHub Actions workflow are described in
+[`ci/README.md`](ci/README.md). Reported CI success requires an actual completed
+workflow run; the presence of the workflow file alone is not evidence of it.
+
+## Minimal working example
+
+```python
+from cranebench.reference import Manoeuvre
+from cranebench.runner import Campaign, run_single
+from cranebench.controllers import LQR
+
+camp = Campaign(plant="planar", wind="kaimal",
+                manoeuvre=Manoeuvre(distance=20.0, t_ramp=20.0, t_total=40.0)).build()
+metrics, (t, X, U) = run_single(LQR(), camp, factors=None, wind_seed=7)
+print(metrics["peak_swing"], metrics["residual_swing"])
+```
+
+## Evaluating your own controller
+
+Subclass `Controller`, implement `__call__(t, x) -> u`, and hand it to the
+runner. Nothing else changes: same plants, same seeds, same metrics.
+
+```python
+from cranebench.controllers import Controller
+from cranebench.runner import Campaign, run_campaign
+from cranebench.uncertainty import lhs_design
+from cranebench.controllers import BASELINES
+
+class MyController(Controller):
+    name = "mine"
+    def __call__(self, t, x):
+        ...
+
+camp = Campaign(controllers={**{k: v() for k, v in BASELINES.items()},
+                             "mine": MyController()})
+res = run_campaign(camp, lhs_design(n=500, seed=20260729))
+```
+
+Because the design is paired, `res["mine"]["residual_swing"] -
+res["PD"]["residual_swing"]` is a sample-by-sample contrast, not a difference of
+two independent clouds.
+
+## What is in the box
+
+| Component | Contents |
+|---|---|
+| Plants | planar crane with hoisting; 3-D crane with a yawing payload; cooperative dual crane with a rigid beam on visco-elastic falls |
+| Disturbances | Kaimal spectral synthesis (exact realised variance); Dryden shaping filter (exact ZOH statistics, unbounded support) |
+| Baselines | PD, LQR, ZVD input shaper, boundary-layer SMC, hierarchical SMC |
+| Design | centred Latin hypercube over five multiplicative factors, paired across controllers |
+| Metrics | ISE, settling time, peak/RMS/residual swing, peak/RMS yaw, effort, peak input, command total variation (CTV), bound satisfaction |
+| Statistics | paired bootstrap CI, Wilcoxon signed-rank, running-mean convergence |
+| Provenance | ledger with source hashes, metric hash, every seed, solver and environment |
+| Execution | scalar reference path (all plants) and a batched path for the planar plant that integrates the whole ensemble at once, 70x faster and verified equal to 1.4e-14 |
+
+## Design decisions that are not obvious
+
+Documented in full in [`docs/DESIGN.md`](docs/DESIGN.md). The short list:
+
+* **The wind record lives on its own grid.** If the disturbance realisation is
+  indexed by the integrator step, refining the step changes the disturbance and
+  a step-convergence study can never converge. Ours is synthesised at 100 Hz and
+  interpolated.
+* **Effort excludes the hoist channel.** The hoist carries the static weight, so
+  including it makes every controller's effort equal to `(mg)^2 T` to three
+  digits and destroys the comparison.
+* **The switching function is `tanh`, not `sign`.** With `sign`, the measured
+  effort of a sliding controller is a function of the integrator step.
+* **The metric module is hashed.** Change a metric and old results stop
+  comparing equal, by design.
+* **Kinematic Jacobians use the complex step.** The Coriolis term differentiates
+  the mass matrix, so a finite-difference Jacobian would be differentiated twice
+  and its noise floor would surface in the accelerations at 1e-4.
+* **The batched path is pinned to the scalar one.** A second implementation of
+  the same experiment is a liability unless a test requires the two to agree;
+  `tests/test_batch.py` does, on every metric over a full paired design.
+
+## Verification
+
+The package does not assert its models, it checks them:
+
+* the hand-derived planar equations agree with an independently assembled
+  Lagrangian model to 6e-10 over random states;
+* all three plants conserve energy to better than 1e-10 relative over 3 s with
+  damping removed;
+* the Kaimal record reproduces the target spectrum with log-PSD correlation
+  above 0.95, and its realised variance is exact;
+* the Dryden filter is stationary from its first sample;
+* every reported metric is converged to better than 0.03 % in the integrator
+  step;
+* the batched execution path reproduces the scalar reference path to 1.4e-14 on
+  every metric.
+
+## Reproducing the paper
+
+```bash
+for c in calm reference dryden stress; do
+    python examples/run_batch_campaign.py $c 500
+done
+python examples/summarise_batch.py          # tables
+python examples/make_figures.py             # figures
+```
+
+Six illustrative campaigns across three plants comprise 11,250 closed-loop controller runs. The full reproducibility procedure is documented in `VERIFY.md`.
+
+## Licence
+
+BSD-3-Clause. If you use it, cite the SoftwareX paper (see `CITATION.cff`).

cranebench-0.1.2/README.md

@@ -0,0 +1,139 @@
+# cranebench
+
+
+A reproducible benchmark for the control of underactuated crane systems.
+
+Crane control papers are almost never comparable with one another. Each one
+defines its own plant, its own manoeuvre, its own wind, its own uncertainty
+range and its own metrics, and then reports that the proposed controller beats
+the baselines the authors implemented themselves. `cranebench` fixes the bench
+so that the controller becomes the only thing that varies.
+
+The package contains **no novel controller**. That is deliberate. Its content
+is the plants, the disturbance models, the paired uncertainty design, the frozen
+metric module, the provenance ledger and five classical baselines.
+
+## Install
+
+```bash
+python -m pip install ".[dev]"
+python -m pytest -q
+```
+
+These commands apply to the source checkout. The separately supplied article
+reproducibility bundle contains retained campaign data and the revision audit.
+Installing the library alone does not install those campaign archives.
+
+Requires Python >= 3.10, NumPy >= 1.24 and SciPy >= 1.10.
+
+The development build `0.1.2.dev0` was uploaded to TestPyPI and the wheel was
+installed from that test index in a clean environment. TestPyPI is separate from
+the production PyPI index. The versioned source distribution is published with the GitHub release, and that same release is archived on Zenodo. A package-name installation route is available from the production PyPI index after publication.
+Compatibility profiles and the GitHub Actions workflow are described in
+[`ci/README.md`](ci/README.md). Reported CI success requires an actual completed
+workflow run; the presence of the workflow file alone is not evidence of it.
+
+## Minimal working example
+
+```python
+from cranebench.reference import Manoeuvre
+from cranebench.runner import Campaign, run_single
+from cranebench.controllers import LQR
+
+camp = Campaign(plant="planar", wind="kaimal",
+                manoeuvre=Manoeuvre(distance=20.0, t_ramp=20.0, t_total=40.0)).build()
+metrics, (t, X, U) = run_single(LQR(), camp, factors=None, wind_seed=7)
+print(metrics["peak_swing"], metrics["residual_swing"])
+```
+
+## Evaluating your own controller
+
+Subclass `Controller`, implement `__call__(t, x) -> u`, and hand it to the
+runner. Nothing else changes: same plants, same seeds, same metrics.
+
+```python
+from cranebench.controllers import Controller
+from cranebench.runner import Campaign, run_campaign
+from cranebench.uncertainty import lhs_design
+from cranebench.controllers import BASELINES
+
+class MyController(Controller):
+    name = "mine"
+    def __call__(self, t, x):
+        ...
+
+camp = Campaign(controllers={**{k: v() for k, v in BASELINES.items()},
+                             "mine": MyController()})
+res = run_campaign(camp, lhs_design(n=500, seed=20260729))
+```
+
+Because the design is paired, `res["mine"]["residual_swing"] -
+res["PD"]["residual_swing"]` is a sample-by-sample contrast, not a difference of
+two independent clouds.
+
+## What is in the box
+
+| Component | Contents |
+|---|---|
+| Plants | planar crane with hoisting; 3-D crane with a yawing payload; cooperative dual crane with a rigid beam on visco-elastic falls |
+| Disturbances | Kaimal spectral synthesis (exact realised variance); Dryden shaping filter (exact ZOH statistics, unbounded support) |
+| Baselines | PD, LQR, ZVD input shaper, boundary-layer SMC, hierarchical SMC |
+| Design | centred Latin hypercube over five multiplicative factors, paired across controllers |
+| Metrics | ISE, settling time, peak/RMS/residual swing, peak/RMS yaw, effort, peak input, command total variation (CTV), bound satisfaction |
+| Statistics | paired bootstrap CI, Wilcoxon signed-rank, running-mean convergence |
+| Provenance | ledger with source hashes, metric hash, every seed, solver and environment |
+| Execution | scalar reference path (all plants) and a batched path for the planar plant that integrates the whole ensemble at once, 70x faster and verified equal to 1.4e-14 |
+
+## Design decisions that are not obvious
+
+Documented in full in [`docs/DESIGN.md`](docs/DESIGN.md). The short list:
+
+* **The wind record lives on its own grid.** If the disturbance realisation is
+  indexed by the integrator step, refining the step changes the disturbance and
+  a step-convergence study can never converge. Ours is synthesised at 100 Hz and
+  interpolated.
+* **Effort excludes the hoist channel.** The hoist carries the static weight, so
+  including it makes every controller's effort equal to `(mg)^2 T` to three
+  digits and destroys the comparison.
+* **The switching function is `tanh`, not `sign`.** With `sign`, the measured
+  effort of a sliding controller is a function of the integrator step.
+* **The metric module is hashed.** Change a metric and old results stop
+  comparing equal, by design.
+* **Kinematic Jacobians use the complex step.** The Coriolis term differentiates
+  the mass matrix, so a finite-difference Jacobian would be differentiated twice
+  and its noise floor would surface in the accelerations at 1e-4.
+* **The batched path is pinned to the scalar one.** A second implementation of
+  the same experiment is a liability unless a test requires the two to agree;
+  `tests/test_batch.py` does, on every metric over a full paired design.
+
+## Verification
+
+The package does not assert its models, it checks them:
+
+* the hand-derived planar equations agree with an independently assembled
+  Lagrangian model to 6e-10 over random states;
+* all three plants conserve energy to better than 1e-10 relative over 3 s with
+  damping removed;
+* the Kaimal record reproduces the target spectrum with log-PSD correlation
+  above 0.95, and its realised variance is exact;
+* the Dryden filter is stationary from its first sample;
+* every reported metric is converged to better than 0.03 % in the integrator
+  step;
+* the batched execution path reproduces the scalar reference path to 1.4e-14 on
+  every metric.
+
+## Reproducing the paper
+
+```bash
+for c in calm reference dryden stress; do
+    python examples/run_batch_campaign.py $c 500
+done
+python examples/summarise_batch.py          # tables
+python examples/make_figures.py             # figures
+```
+
+Six illustrative campaigns across three plants comprise 11,250 closed-loop controller runs. The full reproducibility procedure is documented in `VERIFY.md`.
+
+## Licence
+
+BSD-3-Clause. If you use it, cite the SoftwareX paper (see `CITATION.cff`).

cranebench-0.1.2/cranebench/__init__.py

@@ -0,0 +1,38 @@
+"""
+cranebench -- a reproducible benchmark for underactuated crane control.
+
+The package deliberately contains *baseline* controllers and *infrastructure*
+only. It fixes the plants, the disturbance models, the uncertainty design, the
+frozen metric module and the seed ledger, so that any new controller can be
+evaluated on the same bench against the same realisations.
+
+Design rules (docs/DESIGN.md):
+
+1. The metric module is frozen. Metrics are computed by a single function whose
+   source hash is recorded in every result file.
+2. Plants are pure: derivatives depend only on (t, state, input, disturbance,
+   parameters). No controller may mutate plant state.
+3. Every stochastic quantity comes from an explicitly seeded generator whose
+   seed is written to the ledger.
+4. Uncertainty realisations are drawn once and reused across controllers, so
+   every comparison is paired.
+"""
+
+__version__ = "0.1.2"
+
+from .metrics import METRIC_HASH, Metrics, compute_metrics
+from .uncertainty import UncertaintyDesign, lhs_design
+from .ledger import Ledger
+from .runner import run_campaign, run_single
+
+__all__ = [
+    "__version__",
+    "METRIC_HASH",
+    "Metrics",
+    "compute_metrics",
+    "UncertaintyDesign",
+    "lhs_design",
+    "Ledger",
+    "run_campaign",
+    "run_single",
+]

cranebench-0.1.2/cranebench/batch.py

@@ -0,0 +1,338 @@
+"""Batched campaign path for the planar plant.
+
+The scalar path of :mod:`cranebench.runner` is the reference implementation:
+readable, general over all three plants, and the one the verification tests are
+written against.  It is also slow -- roughly 0.8 s per 40 s run -- which puts a
+2500-run campaign at about half an hour of single-core time and a 10^4-sample
+campaign out of reach.
+
+This module integrates the whole Monte Carlo ensemble at once: the state is an
+``(N, nx)`` array, the plant parameters are ``(N,)`` arrays, and one RK4 step
+advances every sample together.  The controllers are the same control laws
+written elementwise.  Gains that require a per-sample setup (the LQR
+linearisation and Riccati solution, the equilibrium input, the ZVD shaper
+timing) are computed by calling the *scalar* code on a scalar plant built from
+that sample's parameters, so the batched path cannot drift away from the
+reference by re-deriving them.
+
+``tests/test_batch.py`` asserts that the two paths agree to 1e-9 on every metric
+over a full paired design.  Only the planar plant is batched; the assembled
+spatial and dual plants keep the scalar path.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass
+from typing import Dict, List
+
+import numpy as np
+
+from .controllers.base import input_matrix, state_matrix, trim
+from .metrics import compute_metrics
+from .plants import PlanarCrane
+from .plants.planar import G
+from .reference import Manoeuvre
+from .uncertainty import apply_factors
+from .wind import WIND_PARAMS, WINDS
+
+FIELDS = ("m_trolley", "m_payload", "m_winch", "b_x", "b_l", "c_theta",
+          "l0", "area", "cd")
+
+
+# --------------------------------------------------------------------- #
+# plant
+# --------------------------------------------------------------------- #
+@dataclass
+class BatchPlanar:
+    """Planar crane replicated over ``N`` parameter samples."""
+
+    n: int
+    par: Dict[str, np.ndarray]
+    u_max: np.ndarray                      # (N, 2)
+
+    @classmethod
+    def from_samples(cls, plants: List[PlanarCrane]):
+        par = {f: np.array([getattr(p.p, f) for p in plants], float)
+               for f in FIELDS}
+        u_max = np.array([p.p.u_max for p in plants], float)
+        return cls(len(plants), par, u_max)
+
+    def initial_state(self) -> np.ndarray:
+        X = np.zeros((self.n, 6))
+        X[:, 1] = self.par["l0"]
+        return X
+
+    def dynamics(self, t, X, U, fw):
+        p = self.par
+        l = np.maximum(X[:, 1], 1e-3)
+        th = X[:, 2]
+        xd, ld, thd = X[:, 3], X[:, 4], X[:, 5]
+        s, c = np.sin(th), np.cos(th)
+        m, mt, mw = p["m_payload"], p["m_trolley"], p["m_winch"]
+
+        M = np.empty((self.n, 3, 3))
+        M[:, 0, 0] = mt + m
+        M[:, 0, 1] = M[:, 1, 0] = m * s
+        M[:, 0, 2] = M[:, 2, 0] = m * l * c
+        M[:, 1, 1] = m + mw
+        M[:, 1, 2] = M[:, 2, 1] = 0.0
+        M[:, 2, 2] = m * l * l
+
+        rhs = np.empty((self.n, 3))
+        Uc = np.clip(U, -self.u_max, self.u_max)
+        # generalised forces: drives, damping, wind through the payload Jacobian
+        rhs[:, 0] = Uc[:, 0] - p["b_x"] * xd + fw
+        rhs[:, 1] = Uc[:, 1] - p["b_l"] * ld + fw * s
+        rhs[:, 2] = -p["c_theta"] * thd + fw * l * c
+        # Coriolis / centrifugal
+        rhs[:, 0] -= 2.0 * m * ld * thd * c - m * l * thd * thd * s
+        rhs[:, 1] -= -m * l * thd * thd
+        rhs[:, 2] -= 2.0 * m * l * ld * thd
+        # gravity
+        rhs[:, 1] -= -m * G * c
+        rhs[:, 2] -= m * G * l * s
+
+        qdd = np.linalg.solve(M, rhs[:, :, None])[:, :, 0]
+        return np.concatenate([X[:, 3:], qdd], axis=1)
+
+    def payload_velocity_x(self, X):
+        """Horizontal payload velocity for the relative-wind drag law."""
+        l, th = X[:, 1], X[:, 2]
+        return X[:, 3] + X[:, 4] * np.sin(th) + l * X[:, 5] * np.cos(th)
+
+    def outputs(self, X):
+        return {"cart": X[:, 0], "swing": X[:, 2],
+                "yaw": np.zeros(X.shape[0])}
+
+
+# --------------------------------------------------------------------- #
+# controllers
+# --------------------------------------------------------------------- #
+class BatchController:
+    name = "base"
+
+    def setup(self, plants, man, batch):
+        self.plants, self.man, self.b = plants, man, batch
+        self.X0 = batch.initial_state()
+        self.u_eq = np.array([trim(p)[1] for p in plants], float)
+
+    def __call__(self, t, X):
+        raise NotImplementedError
+
+
+class BPD(BatchController):
+    name = "PD"
+
+    def __init__(self, ref):
+        self.r = ref                       # the scalar controller, for its gains
+
+    def _pd(self, t, X, pos, vel):
+        r = self.r
+        U = self.u_eq.copy()
+        U[:, 0] += r.kp * (pos - X[:, 0]) + r.kd * (vel - X[:, 3])
+        rope = self.X0[:, 1] + self.man.hoist * self.man._s(t)
+        U[:, 1] += r.kph * (rope - X[:, 1]) + r.kdh * (self.man.rope_rate(t) - X[:, 4])
+        return U
+
+    def __call__(self, t, X):
+        return self._pd(t, X, self.man.position(t), self.man.velocity(t))
+
+
+class BZVD(BPD):
+    name = "ZVD"
+
+    def setup(self, plants, man, batch):
+        super().setup(plants, man, batch)
+        r = self.r
+        z = r.zeta
+        wn = np.sqrt(G / np.maximum(self.X0[:, 1], 1e-3))
+        wd = wn * np.sqrt(max(1.0 - z * z, 1e-9))
+        K = np.exp(-z * np.pi / np.sqrt(max(1.0 - z * z, 1e-9)))
+        self.amp = np.stack([np.full(batch.n, 1.0), np.full(batch.n, 2.0 * K),
+                             np.full(batch.n, K * K)], 1) / (1.0 + K) ** 2
+        self.tau = np.stack([np.zeros(batch.n), np.pi / wd, 2.0 * np.pi / wd], 1)
+        self.r = r.inner                   # inner PD carries the tracking gains
+        self.r.kph, self.r.kdh = r.inner.kph, r.inner.kdh
+
+    def __call__(self, t, X):
+        td = t - self.tau
+        pos = np.sum(self.amp * self.man.position_v(td), axis=1)
+        vel = np.sum(self.amp * self.man.velocity_v(td), axis=1)
+        return self._pd(t, X, pos, vel)
+
+
+class BLQR(BatchController):
+    name = "LQR"
+
+    def __init__(self, ref):
+        self.r = ref
+
+    def setup(self, plants, man, batch):
+        super().setup(plants, man, batch)
+        from scipy.linalg import solve_continuous_are
+        r = self.r
+        Ks = []
+        for i, p in enumerate(plants):
+            x0, ue = p.initial_state(), self.u_eq[i]
+            A = state_matrix(p, x0, ue)
+            B = input_matrix(p, x0, ue)
+            q = np.full(p.nx, r.q_rate)
+            for j in p.actuated:
+                q[j] = r.q_pos
+            for j in p.unactuated:
+                q[j] = r.q_swing
+            R = np.eye(p.nu) * r.r
+            P = solve_continuous_are(A, B, np.diag(q), R)
+            Ks.append(np.linalg.solve(R, B.T @ P))
+        self.K = np.array(Ks)
+
+    def __call__(self, t, X):
+        Xr = self.X0.copy()
+        Xr[:, 0] = self.man.position(t)
+        Xr[:, 3] = self.man.velocity(t)
+        Xr[:, 1] = self.X0[:, 1] + self.man.hoist * self.man._s(t)
+        Xr[:, 4] = self.man.rope_rate(t)
+        return self.u_eq - np.einsum("nij,nj->ni", self.K, X - Xr)
+
+
+class BSMC(BatchController):
+    name = "SMC"
+
+    def __init__(self, ref):
+        self.r = ref
+
+    def _surfaces(self, t, X):
+        r, man = self.r, self.man
+        s0 = (X[:, 3] - man.velocity(t)) + r.c * (X[:, 0] - man.position(t))
+        rope = self.X0[:, 1] + man.hoist * man._s(t)
+        s1 = (X[:, 4] - man.rope_rate(t)) + r.ch * (X[:, 1] - rope)
+        return s0, s1
+
+    def __call__(self, t, X):
+        r = self.r
+        s0, s1 = self._surfaces(t, X)
+        U = self.u_eq.copy()
+        U[:, 0] += -r.k * s0 - r.eta * np.tanh(s0 / r.phi)
+        U[:, 1] += -r.kh * s1 - r.etah * np.tanh(s1 / r.phi)
+        return U
+
+
+class BHSMC(BSMC):
+    name = "HSMC"
+
+    def __call__(self, t, X):
+        r = self.r
+        s0, s1 = self._surfaces(t, X)
+        s0 = s0 + r.lam * (X[:, 5] + r.c_swing * X[:, 2])
+        U = self.u_eq.copy()
+        U[:, 0] += -r.k * s0 - r.eta * np.tanh(s0 / r.phi)
+        U[:, 1] += -r.kh * s1 - r.etah * np.tanh(s1 / r.phi)
+        return U
+
+
+BATCH_OF = {"PD": BPD, "LQR": BLQR, "ZVD": BZVD, "SMC": BSMC, "HSMC": BHSMC}
+
+
+# --------------------------------------------------------------------- #
+# campaign
+# --------------------------------------------------------------------- #
+def _build(design, campaign):
+    plants, winds = [], []
+    base_p = PlanarCrane().p.__class__()
+    base_w = WIND_PARAMS.get(campaign.wind, WIND_PARAMS["kaimal"])()
+    for i, fac in enumerate(design.as_dicts()):
+        pp, wp = apply_factors(copy.deepcopy(base_p), copy.deepcopy(base_w), fac)
+        plants.append(PlanarCrane(pp))
+        if campaign.wind not in (None, "none"):
+            rng = np.random.default_rng(int(design.wind_seeds[i]))
+            winds.append(WINDS[campaign.wind](campaign.manoeuvre.t_total, wp, rng))
+    return plants, winds
+
+
+def run_campaign_batch(campaign, design, progress=True, relative=True,
+                       rate_limit=True, rate_scale=1.0):
+    """Integrate the whole ensemble at once; returns the same dict as the scalar path."""
+    campaign.build()
+    man = campaign.manoeuvre
+    dt = campaign.dt
+    plants, winds = _build(design, campaign)
+    batch = BatchPlanar.from_samples(plants)
+    n = design.n
+
+    if winds:
+        grid_dt = winds[0].dt
+        turb = np.array([w.turb for w in winds])          # (N, ngrid)
+        u_mean = np.array([w.p.u_mean for w in winds])
+        ngrid = turb.shape[1]
+    rho = 1.225
+    kdrag = 0.5 * rho * batch.par["cd"] * batch.par["area"]
+
+    def wind_force(t, X=None):
+        if not winds:
+            return np.zeros(n)
+        s = t / grid_dt
+        i = int(s)
+        if i < 0:
+            v = u_mean + turb[:, 0]
+        elif i >= ngrid - 1:
+            v = u_mean + turb[:, -1]
+        else:
+            f = s - i
+            v = u_mean + (1 - f) * turb[:, i] + f * turb[:, i + 1]
+        if X is not None and relative:
+            v = v - batch.payload_velocity_x(X)
+        return kdrag * v * np.abs(v)
+
+    nt = int(round(man.t_total / dt)) + 1
+    tgrid = np.arange(nt) * dt
+    every = max(1, int(round(campaign.control_dt / dt)))
+
+    out = {}
+    for cname, scalar_ctrl in campaign.controllers.items():
+        ctrl = BATCH_OF[cname](scalar_ctrl)
+        ctrl.setup(plants, man, batch)
+        X = batch.initial_state()
+        cart = np.empty((n, nt))
+        swing = np.empty((n, nt))
+        Uh = np.empty((n, nt, 2))
+        u_rate = (np.asarray(plants[0].p.u_rate, float) * rate_scale
+                  if rate_limit else None)
+        U = ctrl(0.0, X)
+        for k in range(nt):
+            if k % every == 0:
+                cmd = ctrl(tgrid[k], X)
+                if u_rate is not None:
+                    lim = u_rate * campaign.control_dt
+                    U = U + np.clip(cmd - U, -lim, lim)
+                else:
+                    U = cmd
+            cart[:, k], swing[:, k] = X[:, 0], X[:, 2]
+            Uh[:, k] = U
+            if k == nt - 1:
+                break
+            t = tgrid[k]
+            # the disturbance is frozen across the four RK4 stages, exactly as
+            # the scalar reference path does it; re-evaluating it mid-stage
+            # would be defensible but would no longer be the same experiment
+            fw = wind_force(t, X)
+            k1 = batch.dynamics(t, X, U, fw)
+            k2 = batch.dynamics(t + .5 * dt, X + .5 * dt * k1, U, fw)
+            k3 = batch.dynamics(t + .5 * dt, X + .5 * dt * k2, U, fw)
+            k4 = batch.dynamics(t + dt, X + dt * k3, U, fw)
+            X = X + (dt / 6.0) * (k1 + 2 * k2 + 2 * k3 + k4)
+        ref = man.position_v(tgrid)
+        rows = []
+        for i in range(n):
+            outs = [{"cart": cart[i, k], "swing": swing[i, k], "yaw": 0.0}
+                    for k in range(nt)]
+            rows.append(compute_metrics(tgrid, outs, Uh[i], ref,
+                                        horizontal_inputs=(0,),
+                                        swing_bound_deg=campaign.swing_bound_deg
+                                        ).as_dict())
+        out[cname] = rows
+        if progress:
+            print(f"  {cname}: {n} runs done", flush=True)
+    keys = out[next(iter(out))][0].keys()
+    return {c: {k: np.array([r[k] for r in rows], float) for k in keys}
+            for c, rows in out.items()}

cranebench-0.1.2/cranebench/controllers/__init__.py

@@ -0,0 +1,8 @@
+from .base import Controller, input_matrix, state_matrix, trim
+from .classical import LQR, PD, ZVD
+from .sliding import HSMC, SMC
+
+BASELINES = {"PD": PD, "LQR": LQR, "ZVD": ZVD, "SMC": SMC, "HSMC": HSMC}
+
+__all__ = ["Controller", "PD", "LQR", "ZVD", "SMC", "HSMC", "BASELINES",
+           "trim", "state_matrix", "input_matrix"]