virtualmodelcontrol 0.1.0__py3-none-any.whl

virtualmodelcontrol/core/signals.py

@@ -0,0 +1,46 @@
+"""Signals: named SI arrays stamped with a time, each with a valid flag."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+
+class Signals:
+    """Named SI arrays at time ``t`` [s]; an array counts as valid only if flagged and finite."""
+
+    def __init__(self, t: float = 0.0, **values: ArrayLike) -> None:
+        self.t = float(t)
+        self._data: dict[str, np.ndarray] = {}
+        self._valid: dict[str, bool] = {}
+        for name, value in values.items():
+            self.set(name, value)
+
+    def set(self, name: str, value: ArrayLike, valid: bool = True) -> None:
+        """Store ``value`` (as a 1-D float array) under ``name``."""
+        self._data[name] = np.atleast_1d(np.asarray(value, dtype=float))
+        self._valid[name] = bool(valid)
+
+    def __getitem__(self, name: str) -> np.ndarray:
+        return self._data[name]
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._data
+
+    def get(self, name: str, default: np.ndarray | None = None) -> np.ndarray | None:
+        """Array under ``name``, or ``default``."""
+        return self._data.get(name, default)
+
+    def is_valid(self, name: str) -> bool:
+        """True if present, flagged valid and free of NaN and Inf."""
+        return (
+            name in self._data and self._valid[name] and bool(np.all(np.isfinite(self._data[name])))
+        )
+
+    @property
+    def names(self) -> list[str]:
+        """Names of the stored arrays."""
+        return list(self._data)
+
+    def __repr__(self) -> str:
+        return f"Signals(t={self.t}, {', '.join(self._data)})"

virtualmodelcontrol/core/space.py

@@ -0,0 +1,162 @@
+"""Configuration spaces: q lives on the space (nq numbers), v in its tangent space (nv numbers)."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+import casadi as ca
+import numpy as np
+
+from .symbolic import is_casadi
+
+
+class Space(Protocol):
+    """Where a configuration lives. ``integrate`` and ``difference`` accept numpy or CasADi."""
+
+    nq: int
+    nv: int
+
+    def neutral(self) -> np.ndarray:
+        """Reference configuration (zero displacement)."""
+        ...
+
+    def integrate(self, q: Any, v: Any) -> Any:
+        """Configuration reached from ``q`` by the tangent step ``v``."""
+        ...
+
+    def difference(self, q1: Any, q0: Any) -> Any:
+        """Tangent step ``v`` with ``integrate(q0, v) = q1``."""
+        ...
+
+    def velocity_map(self, q: Any) -> Any:
+        """G(q) with q̇ = G(q) v, shape (nq, nv)."""
+        ...
+
+
+def _numeric_call(fn: Any, *args: Any) -> Any:
+    """Run a CasADi-written ``fn`` on numpy inputs and return numpy; pass CasADi through."""
+    if any(is_casadi(a) for a in args):
+        return fn(*args)
+    out = np.array(fn(*[ca.DM(np.asarray(a, dtype=float).reshape(-1)) for a in args]))
+    return out.ravel() if out.shape[1] == 1 else out
+
+
+class Euclidean:
+    """Flat space: q and v are both n-vectors."""
+
+    def __init__(self, n: int) -> None:
+        self.nq = self.nv = int(n)
+
+    def neutral(self) -> np.ndarray:
+        """Origin."""
+        return np.zeros(self.nq)
+
+    def integrate(self, q: Any, v: Any) -> Any:
+        """``q + v``."""
+        if is_casadi(q) or is_casadi(v):
+            return q + v
+        return np.asarray(q, dtype=float) + np.asarray(v, dtype=float)
+
+    def difference(self, q1: Any, q0: Any) -> Any:
+        """``q1 - q0``."""
+        if is_casadi(q1) or is_casadi(q0):
+            return q1 - q0
+        return np.asarray(q1, dtype=float) - np.asarray(q0, dtype=float)
+
+    def velocity_map(self, q: Any) -> Any:
+        """Identity."""
+        return type(q).eye(self.nq) if is_casadi(q) else np.eye(self.nq)
+
+    def __repr__(self) -> str:
+        return f"Euclidean({self.nq})"
+
+
+class SO2:
+    """Planar rotations as unit complex numbers: q = (cos θ, sin θ), v = angle step (rad)."""
+
+    nq = 2
+    nv = 1
+
+    def neutral(self) -> np.ndarray:
+        """Zero angle."""
+        return np.array([1.0, 0.0])
+
+    def integrate(self, q: Any, v: Any) -> Any:
+        """Rotate ``q`` by the angle ``v``."""
+
+        def fn(q: Any, v: Any) -> Any:
+            c, s, w = q[0], q[1], v[0]
+            return ca.vertcat(c * ca.cos(w) - s * ca.sin(w), s * ca.cos(w) + c * ca.sin(w))
+
+        return _numeric_call(fn, q, v)
+
+    def difference(self, q1: Any, q0: Any) -> Any:
+        """Angle from ``q0`` to ``q1``, in (-π, π]."""
+
+        def fn(q1: Any, q0: Any) -> Any:
+            return ca.atan2(q1[1] * q0[0] - q1[0] * q0[1], q1[0] * q0[0] + q1[1] * q0[1])
+
+        return _numeric_call(fn, q1, q0)
+
+    def velocity_map(self, q: Any) -> Any:
+        """(-sin θ, cos θ) as a column."""
+        if is_casadi(q):
+            return ca.vertcat(-q[1], q[0])
+        c, s = np.asarray(q, dtype=float).ravel()
+        return np.array([[-s], [c]])
+
+    def __repr__(self) -> str:
+        return "SO2()"
+
+
+class Product:
+    """Cartesian product of spaces; q and v are the blocks stacked in order."""
+
+    def __init__(self, *spaces: Space) -> None:
+        self.spaces = spaces
+        self.nq = sum(s.nq for s in spaces)
+        self.nv = sum(s.nv for s in spaces)
+
+    def _blocks(self, x: Any, attr: str) -> list[Any]:
+        out, offset = [], 0
+        for space in self.spaces:
+            n = getattr(space, attr)
+            out.append(x[offset : offset + n])
+            offset += n
+        return out
+
+    @staticmethod
+    def _cat(parts: list[Any]) -> Any:
+        if any(is_casadi(p) for p in parts):
+            return ca.vertcat(*parts)
+        return np.concatenate([np.ravel(p) for p in parts])
+
+    def neutral(self) -> np.ndarray:
+        """Each block's neutral configuration."""
+        return np.concatenate([s.neutral() for s in self.spaces])
+
+    def integrate(self, q: Any, v: Any) -> Any:
+        """Integrate block by block."""
+        qs, vs = self._blocks(q, "nq"), self._blocks(v, "nv")
+        return self._cat([s.integrate(a, b) for s, a, b in zip(self.spaces, qs, vs, strict=True)])
+
+    def difference(self, q1: Any, q0: Any) -> Any:
+        """Difference block by block."""
+        a, b = self._blocks(q1, "nq"), self._blocks(q0, "nq")
+        return self._cat([s.difference(x, y) for s, x, y in zip(self.spaces, a, b, strict=True)])
+
+    def velocity_map(self, q: Any) -> Any:
+        """Block-diagonal G(q)."""
+        qs = self._blocks(q, "nq")
+        blocks = [s.velocity_map(x) for s, x in zip(self.spaces, qs, strict=True)]
+        if any(is_casadi(b) for b in blocks):
+            return ca.diagcat(*blocks)
+        out, i, j = np.zeros((self.nq, self.nv)), 0, 0
+        for block in blocks:
+            r, c = np.shape(block)
+            out[i : i + r, j : j + c] = block
+            i, j = i + r, j + c
+        return out
+
+    def __repr__(self) -> str:
+        return f"Product({', '.join(map(repr, self.spaces))})"

virtualmodelcontrol/core/symbolic.py

@@ -0,0 +1,67 @@
+"""Symbolic helpers shared by the models: type checks, smooth norms, quadrature, rotations."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import casadi as ca
+import numpy as np
+
+
+def is_casadi(x: Any) -> bool:
+    """True for CasADi symbols (SX, MX) and numeric matrices (DM)."""
+    return isinstance(x, (ca.SX, ca.MX, ca.DM))
+
+
+def is_symbolic(x: Any) -> bool:
+    """True for CasADi symbols (SX, MX)."""
+    return isinstance(x, (ca.SX, ca.MX))
+
+
+def smooth_norm(x: Any, eps: float = 1e-18) -> Any:
+    """√(xᵀx + ε): the Euclidean norm, differentiable at zero."""
+    return ca.sqrt(ca.sumsqr(x) + eps)
+
+
+def logcosh(x: Any) -> Any:
+    """log(cosh x), written to avoid overflow for large arguments."""
+    a = ca.fabs(x)
+    return a + ca.log1p(ca.exp(-2.0 * a)) - np.log(2.0)
+
+
+def gauss_legendre(n: int) -> tuple[np.ndarray, np.ndarray]:
+    """Gauss–Legendre nodes and weights on [0, 1], exact for polynomials of degree 2n − 1."""
+    t, w = np.polynomial.legendre.leggauss(n)
+    return 0.5 * (t + 1.0), 0.5 * w
+
+
+def quad(f: Callable[[Any], Any], a: Any, b: Any, n: int = 16) -> Any:
+    """∫ f over [a, b] by n-point Gauss–Legendre quadrature; a, b and f may be symbolic."""
+    t, w = gauss_legendre(n)
+    h = b - a
+    return h * sum(float(wi) * f(a + h * float(ti)) for ti, wi in zip(t, w, strict=True))
+
+
+def skew(w: Any) -> Any:
+    """Skew-symmetric matrix [w]× with [w]× x = w × x."""
+    return ca.vertcat(
+        ca.horzcat(0, -w[2], w[1]),
+        ca.horzcat(w[2], 0, -w[0]),
+        ca.horzcat(-w[1], w[0], 0),
+    )
+
+
+def exp_so3(axis: Any, angle: Any) -> Any:
+    """Rotation by ``angle`` (rad) about the unit vector ``axis`` (Rodrigues)."""
+    k = skew(axis)
+    return ca.DM.eye(3) + ca.sin(angle) * k + (1 - ca.cos(angle)) * ca.mtimes(k, k)
+
+
+def rotation_from_vector(w: Any) -> Any:
+    """Rotation matrix of a rotation vector w (axis · angle [rad]); smooth at w = 0."""
+    theta = ca.sqrt(ca.sumsqr(w) + 1e-24)
+    k = skew(w)
+    return (
+        ca.DM.eye(3) + ca.sin(theta) / theta * k + (1 - ca.cos(theta)) / theta**2 * ca.mtimes(k, k)
+    )

virtualmodelcontrol/core/units.py

@@ -0,0 +1,34 @@
+"""Unit strings for parameters (labels only; every value inside the library is SI)."""
+
+from __future__ import annotations
+
+M = "m"
+RAD = "rad"
+S = "s"
+KG = "kg"
+N = "N"
+NM = "N*m"
+M_S2 = "m/s^2"
+KG_M2 = "kg*m^2"
+
+
+def force_unit(coord_unit: str) -> str:
+    """Unit of the generalized force conjugate to a coordinate of unit ``coord_unit``."""
+    return {M: N, RAD: NM}.get(coord_unit, f"J/{coord_unit}" if coord_unit else "J")
+
+
+def stiffness_unit(coord_unit: str) -> str:
+    """Force per coordinate unit."""
+    return {M: "N/m", RAD: "N*m/rad"}.get(coord_unit, f"J/{coord_unit}^2" if coord_unit else "J")
+
+
+def damping_unit(coord_unit: str) -> str:
+    """Force per coordinate velocity."""
+    return {M: "N*s/m", RAD: "N*m*s/rad"}.get(
+        coord_unit, f"J*s/{coord_unit}^2" if coord_unit else "J*s"
+    )
+
+
+def inertance_unit(coord_unit: str) -> str:
+    """Force per coordinate acceleration."""
+    return {M: KG, RAD: KG_M2}.get(coord_unit, f"J*s^2/{coord_unit}^2" if coord_unit else "J*s^2")

virtualmodelcontrol/dynamics.py

@@ -0,0 +1,149 @@
+"""Robot dynamics assembled from the robot's own components, in the canonical residual form.
+
+M(q) a + h(q, v) − B(q) u − Σ (J G)ᵀ f = 0: inertances give M, the Lagrangian of
+T = ½ vᵀ M v gives h, springs, gravity and dampers give f, the actuation gives B.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+import casadi as ca
+
+from .core.params import Binding, ParamSet
+from .mechanisms.coordinates.base import Context
+from .mechanisms.mechanism import Mechanism
+from .models.actuation import Direct
+
+OPTS = {"cse": True}
+
+
+@dataclass
+class Dynamics:
+    """CasADi functions of a robot's dynamics; p holds its live Params.
+
+    ``forward`` (q, v, u, p, t) → a; ``residual`` (q, v, a, u, p, t) → r; ``mass`` (q, p) → M;
+    ``energy`` (q, v, p, t) → (T, V); ``power`` (q, v, u, p, t) → (input, dissipation, source);
+    ``motors`` (q, v, p) → (θ, θ̇); ``step`` (q, v, u, p, t, h) → (q⁺, v⁺), a linearly implicit
+    Euler step, stable for stiff springs and dampers.
+    """
+
+    robot: Mechanism
+    params: ParamSet
+    live: list[str]
+    forward: ca.Function
+    residual: ca.Function
+    mass: ca.Function
+    energy: ca.Function
+    power: ca.Function
+    motors: ca.Function
+    step: ca.Function
+    n_u: int
+
+    def live_values(self) -> Any:
+        """Current values of the live Params, packed like p."""
+        return self.params.vector(self.live)
+
+
+def compile_dynamics(robot: Mechanism, runtime: Iterable[str] = ()) -> Dynamics:
+    """Compile the dynamics of ``robot`` from its components.
+
+    Valid for spaces whose velocity coordinates commute (Euclidean, SO2 and their products).
+    ``stage`` Params and those matching ``runtime`` stay live; the rest are folded in.
+    """
+    if robot.model is None:
+        raise ValueError(f"robot {robot.name!r} needs a kinematic model")
+    params = ParamSet()
+    params.merge(robot.params, robot.name)
+    binding = Binding(params, params.select(patterns=runtime, scopes=["stage"]))
+    space = robot.model.space
+    actuation = robot.actuation if robot.actuation is not None else Direct()
+    pa = binding.view(actuation.params)
+    n_u = actuation.motor_sizes(space)[1]
+    q, v, a = ca.SX.sym("q", space.nq), ca.SX.sym("v", space.nv), ca.SX.sym("a", space.nv)
+    u, t, h = ca.SX.sym("u", n_u), ca.SX.sym("t"), ca.SX.sym("h")
+    ctx = Context(q, binding, t=t)
+    G = space.velocity_map(q)
+
+    M = ca.SX.zeros(space.nv, space.nv)
+    f_gen = ca.SX.zeros(space.nv, 1)
+    V, P_diss, P_src = ca.SX(0), ca.SX(0), ca.SX(0)
+    for name, comp in robot.components.items():
+        y = ctx.value(comp.coord)
+        J = ca.mtimes(ca.jacobian(y, q), G)
+        if comp.kind == "inertance":
+            M += ca.mtimes([J.T, comp.inertance(ctx, y), J])
+            continue
+        yd = ca.mtimes(J, v) + ca.jacobian(y, t)
+        f = comp.force(ctx, y, yd)
+        f_gen += ca.mtimes(J.T, f)
+        if comp.kind == "storage":
+            V += comp.energy(ctx, y)
+        elif comp.kind == "dissipation":
+            P_diss += ca.dot(f, yd)
+        elif comp.kind == "source":
+            P_src += ca.dot(f, yd)
+        else:
+            raise ValueError(f"{name}: unknown component kind {comp.kind!r}")
+
+    T = 0.5 * ca.dot(v, ca.mtimes(M, v))
+    h_vec = ca.mtimes(ca.jacobian(ca.mtimes(M, v), q), ca.mtimes(G, v)) - ca.mtimes(
+        G.T, ca.gradient(T, q)
+    )
+    tau_u = actuation.generalized_force(u, q, pa)
+    rhs = f_gen + tau_u - h_vec
+    acc = ca.solve(M, rhs)
+
+    # Linearly implicit Euler: (M − h ∂f/∂v − h² ∂f/∂q G) Δv = h (rhs + h ∂f/∂q G v). Only the
+    # component and input forces f are linearized (stiffness and damping); the velocity-squared
+    # terms h stay explicit, which keeps the step first order and cheap.
+    f_lin = f_gen + tau_u
+    dq = ca.mtimes(ca.jacobian(f_lin, q), G)
+    dv = ca.jacobian(f_lin, v)
+    delta_v = ca.solve(M - h * dv - h**2 * dq, h * (rhs + h * ca.mtimes(dq, v)))
+    v_next = v + delta_v
+    q_next = space.integrate(q, h * v_next)
+
+    p = binding.p
+    theta = actuation.motor_angles(q, pa)
+    theta_dot = actuation.motor_rates(q, v, pa)
+    return Dynamics(
+        robot=robot,
+        params=params,
+        live=binding.live,
+        forward=ca.Function(
+            "forward", [q, v, u, p, t], [acc], ["q", "v", "u", "p", "t"], ["a"], OPTS
+        ),
+        residual=ca.Function(
+            "residual",
+            [q, v, a, u, p, t],
+            [ca.mtimes(M, a) - rhs],
+            ["q", "v", "a", "u", "p", "t"],
+            ["r"],
+            OPTS,
+        ),
+        mass=ca.Function("mass", [q, p], [M], ["q", "p"], ["M"], OPTS),
+        energy=ca.Function("energy", [q, v, p, t], [T, V], ["q", "v", "p", "t"], ["T", "V"], OPTS),
+        power=ca.Function(
+            "power",
+            [q, v, u, p, t],
+            [ca.dot(tau_u, v), P_diss, P_src],
+            ["q", "v", "u", "p", "t"],
+            ["input", "dissipation", "source"],
+            OPTS,
+        ),
+        motors=ca.Function(
+            "motors", [q, v, p], [theta, theta_dot], ["q", "v", "p"], ["theta", "theta_dot"], OPTS
+        ),
+        step=ca.Function(
+            "step",
+            [q, v, u, p, t, h],
+            [q_next, v_next],
+            ["q", "v", "u", "p", "t", "h"],
+            ["q_next", "v_next"],
+            OPTS,
+        ),
+        n_u=n_u,
+    )

virtualmodelcontrol/mechanisms/__init__.py

@@ -0,0 +1,67 @@
+"""Mechanisms: coordinates and the components that act on them."""
+
+from .components import (
+    KINDS,
+    Component,
+    ForceSource,
+    GaussianSpring,
+    Gravity,
+    GravityCompensation,
+    Inertance,
+    LimitSpring,
+    LinearDamper,
+    LinearSpring,
+    PointMass,
+    PolynomialSpring,
+    SigmoidSpring,
+    TanhDamper,
+    TanhSpring,
+)
+from .coordinates import (
+    Context,
+    Coordinate,
+    Custom,
+    Difference,
+    FramePoint,
+    Joint,
+    Norm,
+    Projection,
+    Ref,
+    Slice,
+    Stack,
+    State,
+    walk,
+)
+from .mechanism import Mechanism
+
+__all__ = [
+    "KINDS",
+    "Component",
+    "Context",
+    "Coordinate",
+    "Custom",
+    "Difference",
+    "ForceSource",
+    "FramePoint",
+    "GaussianSpring",
+    "Gravity",
+    "GravityCompensation",
+    "Inertance",
+    "Joint",
+    "LimitSpring",
+    "LinearDamper",
+    "LinearSpring",
+    "Mechanism",
+    "Norm",
+    "PointMass",
+    "PolynomialSpring",
+    "Projection",
+    "Ref",
+    "SigmoidSpring",
+    "Slice",
+    "Stack",
+    "State",
+    "TanhDamper",
+    "TanhSpring",
+    "walk",
+]

virtualmodelcontrol/mechanisms/components/__init__.py

@@ -0,0 +1,33 @@
+"""Components: storage (springs), dissipation (dampers), inertance (masses) and sources."""
+
+from .base import KINDS, Component
+from .dissipation import LinearDamper, TanhDamper
+from .inertance import Inertance, PointMass
+from .sources import ForceSource, GravityCompensation
+from .storage import (
+    GaussianSpring,
+    Gravity,
+    LimitSpring,
+    LinearSpring,
+    PolynomialSpring,
+    SigmoidSpring,
+    TanhSpring,
+)
+
+__all__ = [
+    "KINDS",
+    "Component",
+    "ForceSource",
+    "GaussianSpring",
+    "Gravity",
+    "GravityCompensation",
+    "Inertance",
+    "LimitSpring",
+    "LinearDamper",
+    "LinearSpring",
+    "PointMass",
+    "PolynomialSpring",
+    "SigmoidSpring",
+    "TanhDamper",
+    "TanhSpring",
+]

virtualmodelcontrol/mechanisms/components/base.py

@@ -0,0 +1,71 @@
+"""Component base class: something acting on one coordinate, of one of four kinds."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+import casadi as ca
+import numpy as np
+
+from ...core.params import Param, Scope, as_param
+from ..coordinates.base import Context, Coordinate
+
+KINDS = ("storage", "dissipation", "inertance", "source")
+
+
+def scaled(gain: Any, x: Any) -> Any:
+    """Gain times x: a scalar or per-axis gain multiplies entrywise, a matrix multiplies."""
+    return gain * x if gain.shape[1] == 1 else ca.mtimes(gain, x)
+
+
+class Component:
+    """Acts on one coordinate. ``kind`` is storage, dissipation, inertance or source.
+
+    Storage has an energy V(y) and the force f = −∂V/∂y; dissipation has f(y, ẏ) with f·ẏ ≤ 0;
+    inertance has an inertia M(y); a source has a metered force f.
+    """
+
+    kind: ClassVar[str] = ""
+
+    def __init__(self, coord: Coordinate) -> None:
+        self.coord = coord
+        self._params: dict[str, Param] = {}
+
+    def _param(
+        self,
+        name: str,
+        value: Any,
+        *,
+        unit: str,
+        scope: Scope,
+        bounds: tuple[Any, Any] = (0.0, np.inf),
+    ) -> Param:
+        param = as_param(value, name, unit=unit, bounds=bounds, scope=scope)
+        self._params[name] = param
+        return param
+
+    def params(self) -> dict[str, Param]:
+        """Params owned by this component, by local name."""
+        return dict(self._params)
+
+    def energy(self, ctx: Context, y: Any) -> Any:
+        """Stored energy V(y) [J] (storage components)."""
+        raise NotImplementedError(f"{type(self).__name__} stores no energy")
+
+    def force(self, ctx: Context, y: Any, yd: Any) -> Any:
+        """Force on the coordinate, (dim, 1). Storage defaults to −∂V/∂y by differentiation."""
+        if self.kind != "storage":
+            raise NotImplementedError(f"{type(self).__name__} defines no force")
+        if isinstance(y, ca.MX):
+            ym = ca.MX.sym("y", self.coord.dim)
+            return ca.substitute(-ca.gradient(self.energy(ctx, ym), ym), ym, y)
+        ys = ca.SX.sym("y", self.coord.dim)
+        return ca.substitute(-ca.gradient(self.energy(ctx, ys), ys), ys, ca.SX(y))
+
+    def inertance(self, ctx: Context, y: Any) -> Any:
+        """Inertia M(y), (dim, dim) (inertance components)."""
+        raise NotImplementedError(f"{type(self).__name__} has no inertance")
+
+    def __repr__(self) -> str:
+        values = ", ".join(f"{k}={p.value.tolist()}" for k, p in self._params.items())
+        return f"{type(self).__name__}({self.coord!r}, {values})"

virtualmodelcontrol/mechanisms/components/dissipation.py

@@ -0,0 +1,50 @@
+"""Dissipation components: dampers with f(y, ẏ) and f·ẏ ≤ 0."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import casadi as ca
+
+from ...core.registry import register
+from ...core.units import damping_unit
+from ..coordinates.base import Context, Coordinate
+from .base import Component, scaled
+
+
+@register("component", "linear_damper")
+class LinearDamper(Component):
+    """Linear damper, f = −D ẏ.
+
+    ``damping`` D is a scalar, one value per axis, or a matrix [N·s/m, or N·m·s/rad on angles].
+    """
+
+    kind = "dissipation"
+
+    def __init__(self, coord: Coordinate, damping: Any) -> None:
+        super().__init__(coord)
+        self.damping = self._param("damping", damping, unit=damping_unit(coord.unit), scope="stage")
+
+    def force(self, ctx: Context, y: Any, yd: Any) -> Any:
+        """−D ẏ."""
+        return -scaled(ctx.param(self.damping), yd)
+
+
+@register("component", "tanh_damper")
+class TanhDamper(Component):
+    """Saturating damper, per axis: f = −F tanh(d ẏ / F), within ±F on each axis.
+
+    ``damping`` d is the slope at ẏ = 0, a scalar or one value per axis; ``max_force`` F [N].
+    """
+
+    kind = "dissipation"
+
+    def __init__(self, coord: Coordinate, damping: Any, max_force: Any) -> None:
+        super().__init__(coord)
+        self.damping = self._param("damping", damping, unit=damping_unit(coord.unit), scope="stage")
+        self.max_force = self._param("max_force", max_force, unit="N", scope="stage")
+
+    def force(self, ctx: Context, y: Any, yd: Any) -> Any:
+        """−F tanh(d ẏ / F)."""
+        d, F = ctx.param(self.damping), ctx.param(self.max_force)
+        return -F * ca.tanh(d * yd / F)