virtualmodelcontrol 1.2.1__tar.gz → 1.3.0__tar.gz

{virtualmodelcontrol-1.2.1 → virtualmodelcontrol-1.3.0}/CHANGELOG.md

@@ -4,6 +4,103 @@ 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.3.0] - 2026-10-30
+
+A minor release. A plan of a robot with fewer motors than coordinates now reads the motors, as the controller that
+runs does (see Changed), and the result of a review of the whole library: the fixes below, most of them for
+cases that gave a wrong or a silent answer, and the tension floor for tendons that only pull. Nothing else changes
+for a robot with a motor on every coordinate.
+
+### Added
+
+- `control.TensionFloor`: an output stage for tendons that only pull. It lifts the torques of each
+  group of tendons (a segment's three) together until the lowest is at a floor, so no tendon is
+  told to push. Equal torques on evenly spaced tendons only squeeze the segment, so the bend
+  that the command makes is the same. Its corner is rounded, and `symbolic` is the same map for
+  a plan (`Problem(output=)`).
+- `Mechanism.motor` and the `MotorAngle` coordinate: entries of the robot's motor angles, as its
+  actuation gives them. A `LimitSpring` on it is a limit on how far a motor may turn.
+- `helyx.tension_stage`, `helyx.unwind_limit` and their numbers `TENSION_FLOOR`,
+  `UNWIND_LIMIT` and `UNWIND_STIFFNESS`: the tension floor, and a limit on how far a motor may
+  unwind (pulling is free). Both are optional, and `helyx.output_stage` is unchanged.
+- `control.underactuated.Frozen(at=)` and `controller(gravity=<motor angles>)`: the rest of the
+  passive joints balanced once at a pose. The frozen torque stays the gradient of a potential,
+  which `gravity=True` (the balance found again at every reading, as before) does not: its torque
+  has a curl of a few percent in the test. `Frozen.rest` can be set as the `q_rest` of the
+  actuation.
+- A `Param` can be shared by several sections or joints (`PCC([0.2, 0.2], radius)`, one axis for two
+  joints): it keeps one value, `ParamSet.by_name()` lists every name it has, and `select` finds
+  it by any of them (under its own name).
+- `MovingHorizon.encoder` of a robot with fewer motors than coordinates measures the motors, as the
+  Kalman filter's does (it pinned the passive joint at its rest angle: an error of 0.37 rad in the
+  test, 0.001 now). `MovingHorizon.P` is defined from `reset` on.
+- A term of a plan can use a site of a `plant` that is another robot.
+
+### Changed
+
+- A plan of a robot with fewer motors than coordinates now reads the motors, as `VMCController`
+  does (the frozen controller of `control.underactuated`). It used to read the whole state, so
+  that `Problem(system)` and the simulation of `VMCController(compile(system))` were different
+  controllers (a gap of 0.36 rad in the test). `Problem(reads="state")` plans the whole-state
+  controller (`StateController`, `"naive"`), and `reads="motors"` asks for the default outright.
+  For a robot with a motor on every coordinate nothing changes.
+- `MPC` applies a plan only if its solve converged (a real-time iteration is applied as it is):
+  a failed solve used to jump the controller's Params. `MPC.applied` says whether the last plan
+  was, and the next solve after a failed one starts from the measured state. `rti=True` is undone
+  by a later `MPC` of the same problem without it, `reset` drops a plan that is being made, and
+  `start` waits until the last plan was polled.
+- `Result.params` and `Result.steps` are held inside the Params' bounds (the solver relaxes a
+  bound by about 1e-8).
+- `fit_params` and `fit_stiffness_damping` refuse an even `smoothing` (it shifted the derivative by
+  half a sample: a damping of 1.5 came out as 1.88), and a run whose `train` mask is off everywhere.
+  `fit_stiffness_damping` returns NaN, with a warning that names it, for a stiffness or damping
+  that the runs do not determine (it returned 0). `fit_params` takes one name as a string, and
+  a run with nothing to train is skipped when another has samples (an error when none has).
+- `VMCController.set` refuses a value whose size is not the Param's (a scalar was broadcast into a
+  matrix), and `live_params()` returns copies. `balance()` and `elements()` use the Params as
+  `set` left them.
+- `register` replaces a class defined again (a script or a notebook cell run twice) and still
+  refuses another object under a taken name. A plugin that fails to import no longer keeps the
+  others from loading: its error is raised by `get` of a name that is missing (and said in the
+  `KeyError`), and is a warning in `names`.
+- `robot.joint` counts from the end (`slice(0, -1)`) and takes numpy integers; an index out of
+  range is a `ValueError` that says how many coordinates there are.
+- `TensionFloor` needs a positive `width` (zero gave NaN).
+- In `ask` and `tell`, a cost that is not finite (an episode that failed) counts as the worst cost
+  so far (`inf` until one is known) and is never the best; `Bayes` used to fail for good after one.
+- `planar.arm(rest=)` takes one angle per passive joint as well as one per joint.
+- The messages that named `Collocation` and `Equilibrium` name `Shooting` too.
+
+### Fixed
+
+- `Tank`, `SwapController` and `ScheduledController` can be copied and pickled.
+- `Gated` forwards what the wrapped component reads.
+- The docstring of `rollout` says that its `z` rows are the state the law used, one step behind
+  `run`'s.
+
+## [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.
@@ -346,7 +443,7 @@ tank, tuning and the calibrations), which was never released on its own.
     geometric terms out and is not provided.
   - `KalmanFilter(system, dt, Q=None, P0=None, gate=40.0, robot=None)` and `Measurement(q, v, Rq,
     Rv, observed, name)`: a Kalman filter of the robot's state (q, v). Its process model is the
-    robot's own dynamics, linearised at the estimate at rest and held over the step (the lab's
+    robot's own dynamics, linearized at the estimate at rest and held over the step (the lab's
     frozen mass matrix, in general form), with the command going through the system's
     transmission. It fuses encoders (`kf.encoder`) and any sensor that sees part of the state,
     gates each measurement on its innovation, and reports the sensors it rejected (`rejected`,
@@ -437,9 +534,9 @@ tank, tuning and the calibrations), which was never released on its own.
   covariance, on a mass, spring and damper. The tutorial "Fit Params to a run" uses it.
 - `KalmanFilter(..., unscented=True, substeps=10)`: the prediction sends sigma points of the
   estimate (the scaled unscented transform, a root of three standard deviations out) through the
-  robot's own integrator, in `substeps` steps, instead of linearising at the estimate; the sensors
+  robot's own integrator, in `substeps` steps, instead of linearizing at the estimate; the sensors
   stay linear, so the update is the same. On a double pendulum it follows the mean of a Monte
-  Carlo to 0.003 where the linearised prediction is off by 2; on a linear robot the two agree.
+  Carlo to 0.003 where the linearized prediction is off by 2; on a linear robot the two agree.
 - `vmc.estimation.MomentumObserver(system, dt, gain, robot=None)`: the external force on a robot
   from its motion, without accelerations. From the momentum and what the model says would change
   it, it gives the generalized force the model does not explain, as a low-pass filter of bandwidth
@@ -831,7 +928,14 @@ 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.3.0...HEAD
+[1.3.0]: https://github.com/vigno0405/VirtualModelControl/compare/v1.2.2...v1.3.0
+[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.1 → virtualmodelcontrol-1.3.0}/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.3.0
+date-released: "2026-10-30"
 title: "virtualmodelcontrol: Virtual Model Control for robots"
 authors:
   - family-names: Vignoli

{virtualmodelcontrol-1.2.1 → virtualmodelcontrol-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: virtualmodelcontrol
-Version: 1.2.1
+Version: 1.3.0
 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.1 → virtualmodelcontrol-1.3.0}/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.1 → virtualmodelcontrol-1.3.0}/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
@@ -70,7 +94,7 @@ tank
 
 output stage
   An optional correction of the motor commands for real hardware: friction compensation,
-  pretension, an offset or a torque limit.
+  pretension, a tension floor, an offset or a torque limit.
 
 template
   A function that builds a ready-made robot, such as `helyx.arm`, with every geometric number

{virtualmodelcontrol-1.2.1 → virtualmodelcontrol-1.3.0}/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.1 → virtualmodelcontrol-1.3.0}/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.1 → virtualmodelcontrol-1.3.0}/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
 
@@ -34,7 +39,7 @@ change, including that nothing in the library imports ROS.
 | describe a new robot | `vmc.models`: `PCC`, `SerialChain`, `JointSpace`, `LinearCoupling`, `Assembly`, `TendonTransmission` |
 | place virtual elements | `vmc.Mechanism`, coordinates and components such as `vmc.LinearSpring` |
 | compile and run a controller | `vmc.VirtualMechanismSystem`, `vmc.compile`, `vmc.VMCController` |
-| correct commands for real hardware | `vmc.control.output`: friction compensation, pretension, limits |
+| correct commands for real hardware | `vmc.control.output`: friction compensation, pretension, a tension floor, limits |
 | get positions, Jacobians, Hessians | `vmc.Kinematics` |
 | get the robot's equations of motion | `vmc.compile_dynamics` (from the components, or from a function with `vmc.models.Equations`) |
 | simulate a closed loop | `vmc.sim`: `ModelPlant`, `run`, `SimClock` |
@@ -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.1 → virtualmodelcontrol-1.3.0}/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.1 → virtualmodelcontrol-1.3.0}/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.1 → virtualmodelcontrol-1.3.0}/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.1 → virtualmodelcontrol-1.3.0}/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.1 → virtualmodelcontrol-1.3.0}/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