cranebench 0.1.2__py3-none-any.whl

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/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/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"]

cranebench/controllers/base.py

@@ -0,0 +1,62 @@
+"""Controller interface and linearisation helpers.
+
+Every controller in the baseline set is a *published classical* design.  The
+benchmark deliberately contains no novel controller: its purpose is to fix the
+bench, not to compete on it.  A new design is added by subclassing
+:class:`Controller` in the user's own package and passing it to the runner.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+
+class Controller(ABC):
+    name: str = "base"
+
+    def reset(self, plant, manoeuvre) -> None:
+        self.plant = plant
+        self.man = manoeuvre
+        self.x0 = plant.initial_state()
+
+    @abstractmethod
+    def __call__(self, t: float, x: np.ndarray) -> np.ndarray:
+        """Control input at time ``t``.  Must not mutate ``x``."""
+
+
+def input_matrix(plant, x0, u0, h=1e-4):
+    """B = df/du by central differences (dynamics are affine in u, so exact)."""
+    B = np.zeros((plant.nx, plant.nu))
+    for j in range(plant.nu):
+        up, um = np.array(u0, float), np.array(u0, float)
+        up[j] += h
+        um[j] -= h
+        d = np.zeros(3)
+        B[:, j] = (plant.dynamics(0.0, x0, up, d)
+                   - plant.dynamics(0.0, x0, um, d)) / (2 * h)
+    return B
+
+
+def state_matrix(plant, x0, u0, h=1e-6):
+    A = np.zeros((plant.nx, plant.nx))
+    d = np.zeros(3)
+    for j in range(plant.nx):
+        xp, xm = np.array(x0, float), np.array(x0, float)
+        s = h * max(1.0, abs(x0[j]))
+        xp[j] += s
+        xm[j] -= s
+        A[:, j] = (plant.dynamics(0.0, xp, u0, d)
+                   - plant.dynamics(0.0, xm, u0, d)) / (2 * s)
+    return A
+
+
+def trim(plant):
+    """Equilibrium input at the nominal initial state (least squares)."""
+    x0 = plant.initial_state()
+    u0 = np.zeros(plant.nu)
+    f0 = plant.dynamics(0.0, x0, u0, np.zeros(3))
+    B = input_matrix(plant, x0, u0)
+    u_eq, *_ = np.linalg.lstsq(B, -f0, rcond=None)
+    return x0, u_eq

cranebench/controllers/classical.py

@@ -0,0 +1,140 @@
+"""PD, LQR and ZVD input shaping -- the three standard baselines."""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.linalg import solve_continuous_are
+
+from .base import Controller, input_matrix, state_matrix, trim
+
+G = 9.80665
+
+
+class PD(Controller):
+    """Position-only proportional-derivative control on the actuated axes.
+
+    Carries no payload state, and is therefore the control experiment for any
+    claim that a controller "needs" the swing state: whatever a richer design
+    achieves must be measured against what this achieves without it.
+    """
+
+    name = "PD"
+
+    def __init__(self, kp=6.0e3, kd=2.4e4, kp_hoist=4.0e4, kd_hoist=6.0e4):
+        self.kp, self.kd = kp, kd
+        self.kph, self.kdh = kp_hoist, kd_hoist
+
+    def reset(self, plant, manoeuvre):
+        super().reset(plant, manoeuvre)
+        _, self.u_eq = trim(plant)
+
+    def __call__(self, t, x):
+        p, man = self.plant, self.man
+        u = np.array(self.u_eq, float)
+        nq = len(p.state_names) // 2
+        transfer = getattr(p, "transfer_axes", (p.actuated[0],))
+        for k, i in enumerate(p.actuated):
+            if p.state_names[i] == "l":
+                u[k] += (self.kph * (man.rope(t, self.x0[i]) - x[i])
+                         + self.kdh * (man.rope_rate(t) - x[nq + i]))
+            elif i in transfer:
+                # axes that execute the transfer follow it from where they started
+                u[k] += (self.kp * (self.x0[i] + man.position(t) - x[i])
+                         + self.kd * (man.velocity(t) - x[nq + i]))
+            else:
+                u[k] += self.kp * (self.x0[i] - x[i]) + self.kd * (0.0 - x[nq + i])
+        return u
+
+
+class LQR(Controller):
+    """Infinite-horizon LQR on the numerically linearised plant.
+
+    The linearisation point, the weights and the solver are all recorded, so
+    the baseline is reproducible rather than "an LQR we tuned".
+    """
+
+    name = "LQR"
+
+    def __init__(self, q_pos=60.0, q_swing=400.0, q_rate=8.0, r=2.0e-7):
+        self.q_pos, self.q_swing, self.q_rate, self.r = q_pos, q_swing, q_rate, r
+
+    def reset(self, plant, manoeuvre):
+        super().reset(plant, manoeuvre)
+        x0, self.u_eq = trim(plant)
+        A = state_matrix(plant, x0, self.u_eq)
+        B = input_matrix(plant, x0, self.u_eq)
+        nq = plant.nx // 2
+        q = np.full(plant.nx, self.q_rate)
+        for i in plant.actuated:
+            q[i] = self.q_pos
+        for i in plant.unactuated:
+            q[i] = self.q_swing
+        Q = np.diag(q)
+        R = np.eye(plant.nu) * self.r
+        P = solve_continuous_are(A, B, Q, R)
+        self.K = np.linalg.solve(R, B.T @ P)
+        self.nq = nq
+
+    def _xref(self, t):
+        p, man = self.plant, self.man
+        xr = p.reference_state(self.x0, man.position(t), man.velocity(t))
+        for j in p.actuated:
+            if p.state_names[j] == "l":
+                xr[j] = man.rope(t, self.x0[j])
+                xr[self.nq + j] = man.rope_rate(t)
+        return xr
+
+    def __call__(self, t, x):
+        return self.u_eq - self.K @ (x - self._xref(t))
+
+
+class ZVD(Controller):
+    """Zero-vibration-derivative input shaping in cascade with PD tracking.
+
+    The shaper is applied to the *reference*, not to the control signal, which
+    is the standard command-shaping architecture.  It is tuned to the pendulum
+    frequency at the initial rope length and is therefore expected to degrade
+    when the rope length or the payload mass departs from nominal -- that
+    degradation is part of what the benchmark is meant to expose.
+    """
+
+    name = "ZVD"
+
+    def __init__(self, zeta=0.02, kp=6.0e3, kd=2.4e4, kp_hoist=4.0e4, kd_hoist=6.0e4):
+        self.zeta = zeta
+        self.inner = PD(kp, kd, kp_hoist, kd_hoist)
+
+    def reset(self, plant, manoeuvre):
+        super().reset(plant, manoeuvre)
+        self.inner.reset(plant, manoeuvre)
+        l0 = plant.initial_state()[list(plant.state_names).index("l")] \
+            if "l" in plant.state_names else 12.0
+        wn = np.sqrt(G / max(l0, 1e-3))
+        z = self.zeta
+        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)))
+        den = (1.0 + K) ** 2
+        self.amp = np.array([1.0, 2.0 * K, K * K]) / den
+        self.tau = np.array([0.0, np.pi / wd, 2.0 * np.pi / wd])
+
+    def __call__(self, t, x):
+        man = self.man
+        pos = float(np.sum(self.amp * [man.position(t - d) for d in self.tau]))
+        vel = float(np.sum(self.amp * [man.velocity(t - d) for d in self.tau]))
+
+        class _Shaped:
+            def position(_s, tt):
+                return pos
+
+            def velocity(_s, tt):
+                return vel
+
+            rope = man.rope
+            rope_rate = man.rope_rate
+
+        saved = self.inner.man
+        self.inner.man = _Shaped()
+        try:
+            return self.inner(t, x)
+        finally:
+            self.inner.man = saved

cranebench/controllers/sliding.py

@@ -0,0 +1,90 @@
+"""Boundary-layer SMC and hierarchical SMC -- the two sliding baselines.
+
+Both are the textbook forms.  ``SMC`` slides on the actuated tracking error
+only and therefore has no mechanism to damp the payload; ``HSMC`` folds the
+unactuated coordinate into a composite surface, which is the standard
+hierarchical construction.  Neither is a contribution of this package, and the
+gains are exposed so that a user can re-tune them on their own bench.
+
+The switching term uses ``tanh(s / phi)`` rather than ``sign(s)``.  This is not
+cosmetic: with ``sign`` the measured control effort of a sliding controller
+depends on the integrator step, which makes effort comparisons between
+controllers meaningless.  The boundary layer is reported with the results.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import Controller, trim
+
+
+class SMC(Controller):
+    """Sliding-mode control on the actuated coordinates, boundary layer phi."""
+
+    name = "SMC"
+
+    def __init__(self, c=1.1, k=2.2e4, eta=6.0e3, phi=0.06,
+                 c_hoist=2.0, k_hoist=6.0e4, eta_hoist=1.0e4):
+        self.c, self.k, self.eta, self.phi = c, k, eta, phi
+        self.ch, self.kh, self.etah = c_hoist, k_hoist, eta_hoist
+
+    def reset(self, plant, manoeuvre):
+        super().reset(plant, manoeuvre)
+        _, self.u_eq = trim(plant)
+        self.nq = plant.nx // 2
+
+    def _surfaces(self, t, x):
+        p, man, nq = self.plant, self.man, self.nq
+        transfer = getattr(p, "transfer_axes", (p.actuated[0],))
+        s, gains = [], []
+        for k, i in enumerate(p.actuated):
+            if i in transfer:
+                e = x[i] - (self.x0[i] + man.position(t))
+                ed = x[nq + i] - man.velocity(t)
+                s.append(ed + self.c * e)
+                gains.append((self.k, self.eta))
+            elif p.state_names[i] == "l":
+                e = x[i] - man.rope(t, self.x0[i])
+                ed = x[nq + i] - man.rope_rate(t)
+                s.append(ed + self.ch * e)
+                gains.append((self.kh, self.etah))
+            else:
+                e = x[i] - self.x0[i]
+                s.append(x[nq + i] + self.c * e)
+                gains.append((self.k, self.eta))
+        return np.array(s), gains
+
+    def __call__(self, t, x):
+        s, gains = self._surfaces(t, x)
+        u = np.array(self.u_eq, float)
+        for j, (kj, etaj) in enumerate(gains):
+            u[j] += -kj * s[j] - etaj * np.tanh(s[j] / self.phi)
+        return u
+
+
+class HSMC(SMC):
+    """Hierarchical SMC: composite surface S = s_actuated + lam * s_swing.
+
+    The swing sub-surface is ``s_sw = thetad + c_sw * theta``.  Only the first
+    actuated axis carries the composite surface; the remaining axes keep their
+    own first-layer surfaces, which is the usual arrangement for a crane whose
+    hoist is not used for anti-sway.
+    """
+
+    name = "HSMC"
+
+    def __init__(self, lam=0.40, c_swing=1.30, **kw):
+        super().__init__(**kw)
+        self.lam, self.c_swing = lam, c_swing
+
+    def __call__(self, t, x):
+        s, gains = self._surfaces(t, x)
+        theta, theta_dot = self.plant.swing_state(x)
+        s_sw = theta_dot + self.c_swing * theta
+        s = s.copy()
+        s[0] = s[0] + self.lam * s_sw
+        u = np.array(self.u_eq, float)
+        for j, (kj, etaj) in enumerate(gains):
+            u[j] += -kj * s[j] - etaj * np.tanh(s[j] / self.phi)
+        return u