virtualmodelcontrol 1.2.0__tar.gz → 1.2.2__tar.gz

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
 [Semantic Versioning](https://semver.org/) (0.x: the API may change between minor versions).
 
+## [1.2.2] - 2026-10-11
+
+A patch: a fit says when its data do not determine a Param, and gives the same values on every machine; two
+error messages say what to do instead. Nothing else changes.
+
+### Fixed
+
+- `fit_params`: a Param that the data do not determine (a run that never excites it, or an entry of a matrix
+  that only appears in a sum with another, such as the two off-diagonal entries of a spring's stiffness) has
+  `std` `inf`. It was `0.0`, which read as certainty. Along such a direction the fit used to end wherever the
+  rounding of the machine left it (the difference of those two entries came out as 4.06, 3.67 or -2.31 on
+  different CPUs); it now stays at the start, inside the bounds and only if the fit stays as good. The values
+  and the standard errors of the Params that the data do determine are the same as before.
+
+### Changed
+
+- An unknown geometry in `helyx.arm`, `helyx.model` or `helyx.hardware` raises a `KeyError` that names it and
+  lists the known geometries (it was the bare name).
+- The `ValueError` that a law or an estimator raises for a `StateController` now says what to use instead:
+  `underactuated.controller(compiled, "frozen")` without `gravity=True` (that one reads the motors), or
+  `DirectionalForce` for a force. It used to say "the plain frozen controller", which a `gravity=True`
+  controller is not.
+
+## [1.2.1] - 2026-10-10
+
+A patch: a Ctrl-C can no longer lose the log of a real-time run. Nothing else changes.
+
+### Fixed
+
+- A Ctrl-C (or `_thread.interrupt_main()`) that arrived in the middle of a real-time step could land
+  inside a call into CasADi or numpy, come out as a `SystemError` and lose the log. On the main thread,
+  with Python's own handler on SIGINT, `sim.run` now only raises a flag, reads it between two steps and
+  returns the log; a second Ctrl-C raises at once, for a run that is stuck. A handler of your own, and
+  any other thread, are left alone.
+
 ## [1.2.0] - 2026-10-09
 
 A robot that runs for hours: the log of a real-time run can keep only its last seconds. Nothing that
@@ -819,7 +854,13 @@ First public release.
 - `robots.adapt`: the ADAPT finger (two motors, coupled distal joints), joint-angle coordinate
   and joint-limit spring.
 
-[Unreleased]: https://github.com/vigno0405/VirtualModelControl/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/vigno0405/VirtualModelControl/compare/v1.2.2...HEAD
+[1.2.2]: https://github.com/vigno0405/VirtualModelControl/compare/v1.2.1...v1.2.2
+[1.2.1]: https://github.com/vigno0405/VirtualModelControl/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/vigno0405/VirtualModelControl/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/vigno0405/VirtualModelControl/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/vigno0405/VirtualModelControl/compare/v0.5.0...v1.0.0
+[0.5.0]: https://github.com/vigno0405/VirtualModelControl/compare/v0.3.0...v0.5.0
 [0.3.0]: https://github.com/vigno0405/VirtualModelControl/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/vigno0405/VirtualModelControl/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/vigno0405/VirtualModelControl/releases/tag/v0.1.0

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 message: "If you use this software, please cite it as below."
 type: software
-version: 0.3.0
-date-released: "2026-10-05"
+version: 1.2.2
+date-released: "2026-10-11"
 title: "virtualmodelcontrol: Virtual Model Control for robots"
 authors:
   - family-names: Vignoli

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: virtualmodelcontrol
-Version: 1.2.0
+Version: 1.2.2
 Summary: Virtual Model Control: robots and controllers as mechanisms of springs, dampers and inertances, compiled with CasADi.
 Project-URL: Repository, https://github.com/vigno0405/VirtualModelControl
 Project-URL: Documentation, https://vigno0405.github.io/VirtualModelControl/

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/docs/api/index.md

@@ -1,7 +1,10 @@
 # API
 
-Scripts need only `import virtualmodelcontrol as vmc`: the classes and functions of the
-tutorials are available from there. The modules, from the bottom layer up:
+Scripts start with `import virtualmodelcontrol as vmc`: the classes and functions of the
+tutorials, and the modules `vmc.sim`, `vmc.viz` and the others below, are available from there.
+The robot templates are the one exception: import them as
+`from virtualmodelcontrol.robots import helyx` (or `adapt`, `bimanual`, `turtle`). The modules, from
+the bottom layer up:
 
 ```{eval-rst}
 .. autosummary::
@@ -24,4 +27,6 @@ tutorials are available from there. The modules, from the bottom layer up:
    ~virtualmodelcontrol.hardware
    ~virtualmodelcontrol.viz
    ~virtualmodelcontrol.robots
+   ~virtualmodelcontrol.config
+   ~virtualmodelcontrol.testing
 ```

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/docs/concepts/conventions.md

@@ -1,13 +1,17 @@
 # Conventions and glossary
 
+The rules that every part of the library follows, and the words it uses. Read it once, and come back when a sign or a unit surprises you.
+
 ## Units and signs
 
 - SI everywhere: m, rad, s, N, N·m, kg. Degrees stay at the boundary with the hardware, in the
   robot's hardware profile. A driver's raw units (encoder ticks, motor currents) never enter
   the library.
 - A positive motor angle pulls its tendon. Each template states the sign of its robot's
-  encoders against this convention (`helyx.ENCODER_SIGN`, `bimanual.ENCODER_SIGN`,
-  `turtle.MOTOR_SIGNS`); multiply raw readings and commands by it.
+  encoders against this convention (`helyx.ENCODER_SIGN`, one sign for each geometry,
+  `bimanual.ENCODER_SIGN`, one sign, and `turtle.MOTOR_SIGNS`, one sign per motor). The robot's
+  hardware profile applies it for you; if you convert by hand, multiply raw readings and commands
+  by it.
 - Controllers send their torques as computed, never divided by an efficiency. A robot's
   efficiency maps the commanded motor torques to the delivered ones. It is 1 by default,
   because the templates' stiffness and damping were identified from the commanded torques
@@ -17,7 +21,10 @@
 
 - The configuration `q` lives on a space, and the velocity `v` in its tangent space. So `q` and
   `v` may differ in size (a floating body, for example).
-- Motor angles are `θ`, a generalized force is `τ`, actuator commands are `u`.
+- A generalized force is `τ`, actuator commands are `u`. Symbols are local to a page, and each page
+  says what it uses. The one to watch is `θ`: a motor angle in the robot's signals
+  (`motor_position`); a joint angle in the finger and hand pages, where the motors are `q`; the
+  bend of a segment in the PCC page.
 - A spring's deflection is `y = x − x_ref`, so it pulls `x` towards `x_ref`. Storage gives
   `f = −∂V/∂y`, a damper `f = −D ẏ`, and every force reaches the robot as `τ = Jᵀ f`.
 - Arrays in, arrays out: inputs accept anything array-like; outputs are numpy arrays (torch
@@ -25,7 +32,8 @@
 
 ## Continuum robots
 
-- The arc parameter `s ∈ [0, 1]` runs from the base to the tip, uniformly in arc length.
+- The arc parameter `s ∈ [0, 1]` runs from the base to the tip, uniformly in rest length (the arc
+  length while no segment stretches).
 - A segment's configuration is `Δ = (Dx, Dy, Dl)` [m]. The base frame's `z` axis runs along
   the straight body. See [soft-arm kinematics](pcc.md).
 
@@ -56,13 +64,29 @@ virtual state
   A degree of freedom of the controller itself, such as the turtle's flywheel; it needs an
   inertance.
 
+inertance
+  A mass or an inertia on a coordinate, and the component that gives it. A virtual state needs
+  one; a robot has its own.
+
+live Param
+  A Param that may change while the controller runs (scope `stage`), for example with
+  `controller.set`; the others are folded in when the controller is compiled
+  ([parameters](../tutorials/parameters.md)).
+
+law
+  A rule that changes a controller's live Params at every step, such as `ForceTracking`.
+
+guard
+  The check of a run that sends zero torque when a reading is missing, not a number, or too old.
+
 site
   A named point of a kinematic model, such as `"tip"`; continuum models also accept an arc
   parameter `s`.
 
 plant
-  What the controller drives: a simulator such as `ModelPlant`, or the real robot. A planner's
-  plant is the robot that moves, when the controller is written for other coordinates.
+  What the controller drives: a simulator such as `ModelPlant`, or the real robot. In a plan,
+  `Problem(system, plant=robot)` plans the motion of a larger `robot` than the controller's own
+  (see [Optimize](../tutorials/optimize.md)).
 
 tank
   An energy budget for changing a running controller: a change is applied as far as the tank

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/docs/concepts/efficiency.md

@@ -54,21 +54,24 @@ $$
 $$
 
 with each coefficient one value for every motor or one per motor. A number passed as
-`efficiency=` is the linear coefficient $c_1$. `vmc.Efficiency(1.0)` is the default. The
-coefficients are Params, to change, tune or identify:
+`efficiency=` is the linear coefficient $c_1$. `vmc.Efficiency(1.0)` is the default, and
+`Efficiency(..., friction=...)` adds the static friction of the motors
+([Static friction](../tutorials/friction.md)). The coefficients are Params, to change, tune or
+identify:
 
 ```{code-cell} python
 import numpy as np
 import virtualmodelcontrol as vmc
 from virtualmodelcontrol.robots import helyx
 
-cubic = vmc.Efficiency(0.10, 0.0, 0.40)  # one polynomial for every motor
+cubic = vmc.Efficiency(0.10, 0.0, 0.40)  # made-up numbers, for all motors
 arm = helyx.arm(efficiency=cubic)
 arm.params["efficiency.c3"]
 ```
 
 A robot with an efficiency other than 1 receives the delivered torques, so its stiffness,
-damping and masses must be the physical ones, referred to the delivered torque. In a
+damping and masses must be the physical ones, referred to the delivered torque: the values
+identified from the commanded torques, times $\eta$, as above. In a
 simulator, `vmc.sim.ModelPlant(robot, runtime=["*efficiency*"])` keeps the coefficients live.
 
 ## Identify it from static measurements
@@ -96,7 +99,7 @@ holds = plateaus(t, command, tolerance=1e-6)  # settled half of each hold
 u = np.array([command[h].mean() for h in holds])
 y = np.array([measured[h].mean() for h in holds])
 linear = fit_efficiency(u, y)
-cubic = fit_efficiency(u, y, degree=3)
+cubic_fit = fit_efficiency(u, y, degree=3)
 ```
 
 ```{code-cell} python
@@ -108,7 +111,7 @@ grid = np.linspace(0.0, 1.05, 100)
 fig, ax = plt.subplots()
 ax.plot(u, y, "o", color=viz.PALETTE[0], label="plateaus")
 ax.plot(grid, linear(grid), "--", color=viz.PALETTE[1], label="linear fit")
-ax.plot(grid, cubic(grid), color=viz.PALETTE[2], label="cubic fit")
+ax.plot(grid, cubic_fit(grid), color=viz.PALETTE[2], label="cubic fit")
 ax.set_xlabel(r"commanded torque [N$\cdot$m]")
 ax.set_ylabel(r"delivered torque [N$\cdot$m]")
 ax.legend();
@@ -125,8 +128,8 @@ def r2(fit):
 
 glue("eta_linear", float(linear.params["c1"].value[0]), display=False)
 glue("r2_linear", float(r2(linear)), display=False)
-glue("r2_cubic", float(r2(cubic)), display=False)
-glue("c3", float(cubic.params["c3"].value[0]), display=False)
+glue("r2_cubic", float(r2(cubic_fit)), display=False)
+glue("c3", float(cubic_fit.params["c3"].value[0]), display=False)
 ```
 
 The linear fit gives a constant efficiency of {glue:text}`eta_linear:.3f` ($R^2$ =

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/docs/concepts/finger.md

@@ -8,7 +8,7 @@ kernelspec:
 
 The ADAPT finger and hand are rigid chains of phalanges driven through tendons and cables, with
 fewer motors than joints. This page gives the equations of `robots.adapt`: how motor angles set
-joint angles, and how joint angles place the fingertip.
+joint angles, and how joint angles place the fingertip, and then how the hand's motors drive its joints.
 
 ```{code-cell} python
 :tags: [remove-cell]
@@ -33,7 +33,8 @@ glue("pip", float(adapt.COUPLING[1, 1]), display=False)
 
 The finger has three phalanges, proximal, middle and distal, of {glue:text}`a:.1f`,
 {glue:text}`b:.1f` and {glue:text}`c:.1f` mm, joined by three revolute joints, MCP, PIP and
-DIP, all turning about $x$. Straight, it points along $y$. Bending it turns the tip towards $z$.
+DIP (the metacarpophalangeal, proximal interphalangeal and distal interphalangeal joints), all
+turning about $x$. Straight, it points along $y$. Bending it turns the tip towards $z$.
 
 ```{code-cell} python
 :tags: [remove-input]
@@ -45,11 +46,11 @@ schematic.figure();
 
 Two motors drive the three joints. The first pulls a cable on a pulley of the MCP joint. The
 second drives the PIP joint through a cable, and the DIP joint follows the PIP joint. With
-motor angles $q_1, q_2$,
+motor angles $q_0, q_1$,
 
 $$
-\theta_\text{MCP} = \frac{r_p}{r_m}\,q_1, \qquad
-\theta_\text{PIP} = \theta_\text{DIP} = \frac{r_m}{c_p}\,q_2,
+\theta_\text{MCP} = \frac{r_p}{r_m}\,q_0, \qquad
+\theta_\text{PIP} = \theta_\text{DIP} = \frac{r_m}{c_p}\,q_1,
 $$
 
 with $r_m$ the motor pulley's radius, $r_p$ that of the MCP pulley and $c_p$ the cable constant
@@ -100,9 +101,8 @@ glue("spread", ", ".join(coefficients[:3]) + " and " + coefficients[3], display=
 ```
 
 The hand has a thumb and four fingers, each a chain of revolute joints from the hand's base.
-The thumb has the joints CMC1, CMC2, MCP and IP, and each finger has the joints spread, MCP,
-PIP and DIP. The origins and axes of the joints come from the hand's design files, as tables
-of the module.
+The thumb has the joints CMC1, CMC2 (carpometacarpal), MCP and IP (interphalangeal), and each
+finger has the joints spread, MCP, PIP and DIP. The origins and axes of the joints are tables in `robots.adapt` (`HAND_JOINTS`, `HAND_FINGER_BASES`).
 {glue:text}`motors:.0f` motors drive its {glue:text}`joints:.0f` joints, $\theta = C\,q$:
 
 - each thumb joint has a motor of its own;

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/docs/concepts/library.md

@@ -6,8 +6,9 @@ kernelspec:
 
 # How the library is organized
 
-The library is a stack of layers. Each layer uses only the layers below it. The ready-made
-robots and the figures sit at the edges. They may use every layer, and no layer uses them.
+This page is a map: what each part of the library does, and which names to look for. The library
+is a stack of layers. Each layer uses only the layers below it. The ready-made robots and the
+figures sit at the edges. They may use every layer, and no layer uses them.
 
 ```{code-cell} python
 :tags: [remove-cell]
@@ -20,11 +21,15 @@ from schematics import library_map
 library_map.figure();
 ```
 
+From the bottom, the layers are `core` (Params and signals), `math`, `mechanisms`, `models`,
+`system`, `compiler` and `dynamics`, `control`, `sim`, `estimation` and `identification`, and
+`adaptation` and `optimization`. The edges are `robots`, `hardware`, `viz`, `config` and `testing`.
+
 A controller needs only the layers up to `control`: describe the robot with `models`, place
 virtual elements with `mechanisms`, pair them in a `VirtualMechanismSystem`, `compile` it and
 run it with `VMCController`. Simulation, figures and the robot templates are optional.
-`lint-imports` enforces the order: it checks the contracts written in `pyproject.toml` on every
-change, including that nothing in the library imports ROS.
+The order is checked automatically on every change, and so is that nothing in the library imports
+a robot middleware such as ROS: signals come in and go out as arrays.
 
 ## Where things are
 
@@ -46,7 +51,7 @@ change, including that nothing in the library imports ROS.
 | describe an experiment in a file | `vmc.config`: `load`, `Experiment` |
 | draw and animate | `vmc.viz` |
 | run a model without CasADi | `backend="numpy"` or `"torch"`, `Dynamics.export`, `Compiled.export` |
-| parameters, units, scopes | `vmc.Param`, `vmc.ParamSet` |
+| parameters, units, scopes | `vmc.Param`, `vmc.ParamSet` ([Parameters](../tutorials/parameters.md)) |
 
 ## One symbolic source
 
@@ -61,9 +66,11 @@ $$
 \end{aligned}
 $$
 
-with $M$ the mass matrix, $h$ the velocity and gravity terms, $B$ the actuation map, $f_k$ the
-forces of the robot's own components and $J_k$ the Jacobian of each one's coordinate with
-respect to the velocity. A model whose dynamics are not made of such components (a black box)
+with $M$ the mass matrix, $h$ the velocity terms of the kinetic energy (Coriolis and centrifugal),
+$B$ the actuation map, $f_k$ the forces of the robot's own components (springs, dampers, gravity)
+and $J_k$ the Jacobian of each one's coordinate with respect to the velocity. A model whose dynamics are not made of such components (a black box)
 gives the residual itself, as a function. The numpy and PyTorch versions of a model are not
 written again: they are generated from the same graph ([Use a model outside
 CasADi](../tutorials/outside.md)).
+
+To use these parts, start with [your first controller](../tutorials/first-controller.md).

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/docs/concepts/passivity.md

@@ -24,13 +24,13 @@ energy_flow.figure();
 
 ## The controller's energy balance
 
-The controller stores $E_c = V + T$: $V$ in its springs, $T$ in the inertances of its virtual
-states. Three powers change it. The port, $P = \tau^\top v$, is the power its torques give the
-robot. The dissipation is $D = \sum f \cdot \dot y \le 0$ over its dampers. The source power is
-$S = \sum f \cdot \dot y$ over its sources. With the [VMC equations](vmc.md),
+The controller stores $E_c = V + T$: $V$ in its springs, measured from its lowest value so that
+$E_c \ge 0$, and $T$ in the inertances of its virtual states. Three powers change it. The port, $P = \tau^\top v$, is the power its torques give the
+robot. The dissipation power is $P_D = \sum f \cdot \dot y \le 0$ over its dampers. The source power is
+$P_S = \sum f \cdot \dot y$ over its sources. With the [VMC equations](vmc.md),
 
 $$
-\dot E_c = -P + D + S .
+\dot E_c = -P + P_D + P_S .
 $$
 
 The compiled controller computes each term (`compiled.energy`, `compiled.power`), so the balance can be
@@ -41,10 +41,10 @@ checked on any run.
 Without sources, integrating the balance gives
 
 $$
-\int_0^t P\,\mathrm{d}t = E_c(0) - E_c(t) + \int_0^t D\,\mathrm{d}t \;\le\; E_c(0),
+\int_0^t P\,\mathrm{d}t = E_c(0) - E_c(t) + \int_0^t P_D\,\mathrm{d}t \;\le\; E_c(0),
 $$
 
-since $E_c(t) \ge 0$ and $D \le 0$. Whatever the robot does, the controller gives it at most the
+since $E_c(t) \ge 0$ and $P_D \le 0$. Whatever the robot does, the controller gives it at most the
 energy it stored at the start: it is passive.
 
 ## The robot and its controller together
@@ -54,7 +54,7 @@ by its input power and its own dissipation. With the default [efficiency](effici
 and no output stage, its input power is the controller's port $P$, so the two balances add up:
 
 $$
-\dot E_r + \dot E_c = D_r + D + S .
+\dot E_r + \dot E_c = P_{D,r} + P_D + P_S .
 $$
 
 Without sources the total energy can only fall. It is bounded by its value at the start. Where

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/docs/concepts/pcc.md

@@ -24,44 +24,45 @@ pcc.figure();
 
 Segment $i$ has the coordinates $\Delta_i = (D_x, D_y, D_l)$ [m]: $D_x$ and $D_y$ bend it
 towards $(D_x, D_y)$, and $D_l$ lengthens it. With rest length $L_0$, section radius $d$ and
-local arc fraction $s \in [0, 1]$,
+local arc fraction $s \in [0, 1]$, the size of the bend is $\rho$ and its angle at $s$ is $\theta$:
 
 $$
 \begin{gathered}
-D = \sqrt{D_x^2 + D_y^2 + \varepsilon}, \\
-\theta(s) = s\,D/d .
+\rho = \sqrt{D_x^2 + D_y^2 + \varepsilon}, \\
+\theta(s) = s\,\rho/d .
 \end{gathered}
 $$
 
-The frame at $s$ is turned by $\theta$ about the axis $(-D_y, D_x, 0)/D$, and its origin is
+The frame at $s$ is turned by $\theta$ about the axis $(-D_y, D_x, 0)/\rho$, and its origin is
 
 $$
-t(s) = \frac{d\,(L_0 + D_l)}{D^2}
-\begin{bmatrix} D_x (1 - \cos\theta) \\ D_y (1 - \cos\theta) \\ D \sin\theta \end{bmatrix},
+t(s) = \frac{d\,(L_0 + D_l)}{\rho^2}
+\begin{bmatrix} D_x (1 - \cos\theta) \\ D_y (1 - \cos\theta) \\ \rho \sin\theta \end{bmatrix},
 $$
 
-the point at arc length $s\,(L_0 + D_l)$ on an arc of radius $d\,(L_0 + D_l)/D$. The tangent
+the point at arc length $s\,(L_0 + D_l)$ on an arc of radius $d\,(L_0 + D_l)/\rho$. The tangent
 is the frame's $z$ axis. The small $\varepsilon$ ($10^{-12}$ m²) keeps the straight pose
 smooth.
 
 ## The whole arm
 
 The configuration stacks the segments, base to tip: $q = (\Delta_1, \dots, \Delta_n)$. The arc
-parameter $s \in [0, 1]$ of the whole arm is uniform in arc length, so segment $i$ spans
+parameter $s \in [0, 1]$ of the whole arm is uniform in rest length (it is the arc length while no segment stretches), so
+segment $i$ spans
 $[b_{i-1}, b_i]$ with $b_i = \sum_{j \le i} L_{0,j} / \sum_j L_{0,j}$. Each segment's frame
 starts where the previous one ends. `arm.point(s=...)` accepts a symbolic $s$ as well, so an
 attachment point can itself be optimized.
 
 ## Tendons
 
-A tendon at angle $\delta$ around the section and distance $d$ from the backbone changes
-length by
+A tendon at angle $\delta$ around the section changes length by
 
 $$
 \Delta L = D_l - D_x \cos\delta - D_y \sin\delta ,
 $$
 
-and its motor, with spool radius $r$, turns by $\theta_m = -\Delta L / r$: a positive motor
+(the distance $d$ of the tendon from the backbone is already inside $D_x$ and $D_y$), and its motor,
+with spool radius $r$, turns by $\theta_m = -\Delta L / r$: a positive motor
 angle pulls the tendon. With three tendons per segment this map is invertible, so the measured
 motor angles give $\Delta$ exactly. The motor torques that realize a generalized force $\tau$
 solve $B u = \tau$ with $B = (\partial\theta_m/\partial\Delta)^\top$. The transmission's
@@ -70,7 +71,7 @@ ones.
 
 ## The templates
 
-`robots.helyx` builds Helyx arms from these equations. Three geometries are ready: the soft
+`robots.helyx` builds Helyx arms from these equations. Three geometries are ready, named by their segment lengths in mm: the soft
 arm of the [soft-arm example](../examples/soft-arm.md) (on its side), the
 [hanging soft arm](../examples/hanging-arm.md) and the arms of the
 [two-arm example](../examples/two-arms.md). Their segment lengths, their mounting and the sign
@@ -81,12 +82,14 @@ of their encoders against the convention above are:
 from IPython.display import Markdown
 from virtualmodelcontrol.robots import helyx
 
-rows = ["| Geometry | Segments, base to tip | Gravity in the base frame | Encoder sign |",
-        "|---|---|---|---|"]
+used = {"145-145-145": "soft arm", "145-290-290": "hanging arm", "290-145-145": "two arms"}
+rows = ["| Geometry | Used in | Segments, base to tip | Gravity in the base frame | Encoder sign |",
+        "|---|---|---|---|---|"]
 for name, spec in helyx.GEOMETRIES.items():
     lengths = ", ".join(f"{1000 * L:.0f}" for L in spec["L0"]) + " mm"
     gravity = "[" + ", ".join(f"{g:g}" for g in spec["gravity"]) + "] m/s²"
-    rows.append(f"| `{name}` | {lengths} | {gravity} | {helyx.ENCODER_SIGN[name]:+.0f} |")
+    rows.append(f"| `{name}` | {used[name]} | {lengths} | {gravity} "
+                f"| {helyx.ENCODER_SIGN[name]:+.0f} |")
 Markdown("\n".join(rows))
 ```
 
@@ -101,5 +104,5 @@ short = helyx.arm(
     lengths=(0.2, 0.2),  # [m], two segments
     tendon_angles=np.radians([[0, 120, -120], [60, 180, -60]]),
 )
-short.actuation.motor_sizes(short.space)  # motor angles and rates
+short.actuation.motor_sizes(short.space)  # 6 motor angles and 6 rates
 ```

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/docs/concepts/vmc.md

@@ -46,15 +46,15 @@ $J_z$ need no hand derivation.
 ## Elements and their forces
 
 Each element gives a force $f$ on its coordinate. Springs store energy, $f = -\partial V/\partial y$
-with $V \ge 0$. A linear spring of stiffness $K$ on $y = x - x_\text{ref}$ pulls $x$ towards
+with $V$ bounded below. A linear spring of stiffness $K$ on $y = x - x_\text{ref}$ pulls $x$ towards
 $x_\text{ref}$ with $f = -K y$. Dampers dissipate, $f \cdot \dot y \le 0$, as $f = -D \dot y$.
-Inertances give the virtual states their mass. Sources add forces of their own, such as gravity
-compensation, $f = -m g$ on each of the robot's masses.
+Inertances give mass to a virtual state of the controller, or to a coordinate of the robot. Sources add forces of their own, such as gravity
+compensation, $f = -m g$ on each of the robot's masses $m$, with $g$ the gravity vector.
 
 ## From forces to motor torques
 
-The torque that a force $f$ on $y$ exerts on the robot follows from virtual work:
-$f \cdot \delta y = \tau^\top \delta q$ for every small motion, so
+The torque that a force $f$ on $y$ exerts on the robot follows from power:
+$f \cdot \dot y = \tau^\top v$ for every velocity $v$, so
 
 $$
 \tau = \sum_k J_{q,k}^\top f_k ,
@@ -70,8 +70,8 @@ with $B$ the robot's actuation map. For a tendon arm $B = (\partial\theta/\parti
 with $\theta$ the motor angles. With one motor per joint $B$ is the identity. The controller
 never divides $u$ by an [efficiency](efficiency.md). A robot with fewer motors than joints has
 no $u$ that solves it for every $\tau$: the motors give the least-squares
-$u = B^+\tau$, and what they cannot give is the part that
-[the underactuated tutorial](../tutorials/underactuated.md) calls the defect.
+$u = B^+\tau$, and the part of $\tau$ outside the range of $B$, which they cannot give, is the
+torque defect of [the underactuated tutorial](../tutorials/underactuated.md).
 
 ## Virtual states
 

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/docs/conf.py

@@ -52,7 +52,7 @@ intersphinx_mapping = {
 
 html_theme = "sphinx_immaterial"
 html_title = "virtualmodelcontrol"
-html_logo = "_static/logo-light.svg"  # the header is navy in both colour schemes
+html_logo = "_static/logo-light.svg"  # the header is navy in both color schemes
 html_favicon = "_static/favicon.svg"
 # Tooltips of API objects without their synopsis, which the theme joins with an em dash.
 object_description_options = [("py:.*", {"generate_synopses": None})]
@@ -77,7 +77,7 @@ html_theme_options = {
         {
             "media": "(prefers-color-scheme: light)",
             "scheme": "default",
-            "primary": "custom",  # colours in _static/custom.css
+            "primary": "custom",  # colors in _static/custom.css
             "accent": "custom",
             "toggle": {"icon": "material/weather-night", "name": "Dark mode"},
         },

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/docs/development/contributing.md

@@ -1,5 +1,7 @@
 # Contributing
 
+How to set up a working copy, run the checks, and send a change.
+
 ## Set up
 
 From a clone of the repository, on Linux or macOS:
@@ -72,7 +74,9 @@ Pages are MyST notebooks: every code cell runs at each build, and an error fails
 
 Versions follow semantic versioning and come from git tags. To release:
 
-1. In `CHANGELOG.md`, rename "Unreleased" to the new version and date.
+1. In `CHANGELOG.md`, rename "Unreleased" to the new version and date, and add the version's
+   comparison link at the end of the file. Give `CITATION.cff` the same version and date, and the
+   pin example of `docs/installation.md` the new version.
 2. Push `main`, then tag and push the tag:
 
    ```bash

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/docs/development/support.md

@@ -5,9 +5,11 @@ What you can rely on from version 1.0.0 on.
 ## Versions of Python and of the packages
 
 The library runs on Python 3.10 to 3.14, with numpy 1.26 or any 2.x. Every push runs the tests
-on Ubuntu 22.04 and 24.04 with Python 3.10, 3.12 and 3.14. We have also run them from a fresh
-clone on 3.11 and 3.13, and with the oldest versions the library allows: numpy 1.26, SciPy
-1.11, CasADi 3.6 and matplotlib 3.8. PyTorch, which only the models exported as PyTorch code
+on Ubuntu 22.04 with Python 3.10 and on Ubuntu 24.04 with Python 3.12 and 3.14, with numpy 1.26
+and with 2.x (3.14 with 2.x only). One more job runs them on Python 3.10 with the oldest versions
+the library allows: numpy 1.26, SciPy 1.11, CasADi 3.6 and matplotlib 3.8. Before a release the
+tests also run on macOS and Windows, and we have run them from a fresh clone on 3.11 and 3.13.
+PyTorch, which only the models exported as PyTorch code
 need, is tried with its newest release.
 
 A Python version is dropped, in a minor release and with a line in the

{virtualmodelcontrol-1.2.0 → virtualmodelcontrol-1.2.2}/docs/examples/finger.md

@@ -18,7 +18,7 @@ import docs_setup
 
 The ADAPT finger has three phalanges and two motors: motor 0 turns the first joint (MCP)
 through a pulley, and motor 1 turns the other two (PIP and DIP) together through a cable. Its
-configuration is the two motor angles $\theta_0, \theta_1$.
+configuration is the two motor angles $q_0, q_1$.
 
 ```{code-cell} python
 :tags: [remove-input]
@@ -69,7 +69,9 @@ simulated finger can start to vibrate. `adapt.finger(efficiency=adapt.MOTOR_EFFI
 includes the efficiencies.
 
 The template takes its geometry and transmission as arguments. A longer finger with a larger
-pulley on the MCP joint, for example, has a new first coupling ratio:
+pulley on the MCP joint, for example, has a new first coupling ratio: the MCP joint turns by the
+pulley's radius over the motor pulley's per motor angle, $3 / 5 = 0.6$ in place of the default
+2.23 / 5 = 0.446:
 
 ```{code-cell} python
 import numpy as np
@@ -78,7 +80,8 @@ from virtualmodelcontrol.robots import adapt
 
 longer = adapt.finger(link_lengths=(0.045, 0.035, 0.02),  # [m]
                       pulley_radius=0.003)  # [m], on the MCP joint
-longer.params["coupling"].value.round(3)
+default = adapt.finger().params["coupling"].value.round(3)
+default, longer.params["coupling"].value.round(3)  # before and after
 ```
 
 A new pulley comes with a new ratio, which a sweep measures: set the MCP joint to known angles,