virtualmodelcontrol 0.5.0__tar.gz → 1.1.0__tar.gz

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/CHANGELOG.md

@@ -4,7 +4,169 @@ 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).
 
-## [Unreleased]
+## [1.1.0] - 2026-10-09
+
+Static friction of the motors: a model of it, a compensation for it, its identification and a
+tutorial, all off unless asked for. Nothing that worked before changes.
+
+### Added
+
+- Static friction of the motors, off by default. `StaticFriction(breakaway, kinetic, width)`
+  [N·m] is the torque that friction takes from a motor as a smooth function of the torque applied
+  to it: all of it below the breakaway torque F (the motor is stuck), the kinetic torque Fc with
+  the sign of the command past it (Fc = 0: static friction gone once it moves; Fc = F: it stays),
+  smooth (C^∞) over `width`, so solvers differentiate it. It depends on the torque only, not on
+  the speed. `Efficiency(c1, ..., friction=StaticFriction(...))` takes it before the polynomial, so
+  every transmission carries it (`Direct`, `Underactuated`, `TendonTransmission`, stacked ones, and
+  configuration files), and the simulator, `compile_dynamics`, `Collocation`, `Shooting`, `MPC`, the
+  Kalman filter and the force law all have it. Its Params are `friction.breakaway`,
+  `friction.kinetic` and `friction.width`; with F = Fc = 0, the default, nothing changes. Not passive
+  by construction: when a command brakes the motion it can create up to F |θ̇| of power, which the
+  tutorial states and measures.
+- `control.StaticFrictionCompensation(kinetic, width, fraction)` (and `.of(friction, fraction)`), an
+  output stage that adds the kinetic friction torque in the direction of the command, smooth in the
+  command. Against a `StaticFriction(F, Fc)` it delivers the command once the motor moves and
+  narrows the dead band from F to F − Fc. Nothing turns it on but you: no template or controller
+  has it by default. It has a `symbolic` form, so `Problem(system, output=[...])` and
+  `sim.rollout(..., output=[...])` apply it in a plan as `VMCController(output=)` does in a run
+  (`Problem` now raises for an output stage that has no `symbolic` form).
+- Identification of the friction: its Params are the robot's, so `identification.fit_params` fits
+  them, with the stiffness and damping, to a run in which the command rises slowly from rest;
+  `fit_efficiency(commanded, delivered, friction=True, width=)` fits the efficiency and the friction
+  to static torques (per motor or `shared`), by a grid and a refinement over the breakaway and the
+  kinetic torque.
+- `robots.adapt.finger_friction()` and `hand_friction()`: the lab's friction values of the finger
+  (0.20 N·m) and the hand (0.10 N·m) as a `StaticFriction`, to ask for.
+- Docs: the tutorial "Static friction of the motors".
+
+## [1.0.0] - 2026-10-07
+
+The first stable release. It also carries the work meant for 0.6.0 (planning with virtual states,
+unmeasured coordinates, custom dynamics, the planner on a larger plant, MPC and underactuation) and
+for 0.7.0 (models as numpy and PyTorch code), which were never released on their own, and it adds
+the checking: the whole suite on the oldest and the newest supported Python and numpy, on Linux,
+macOS and Windows, every page of the documentation run from a clean checkout, and a review of the
+public API (what `__all__` lists in each module is the API) and of every page of the docs at desktop
+and phone width. The rules for what changes between versions are on the page "Support policy".
+
+### Added
+
+- `optimization.Shooting(q0, horizon, nodes, v0=, steps=, initial=, transition=, scales=,
+  integrator=, substeps=)`: multiple shooting, a second transcription next to `Collocation`
+  with the same terms. The unknowns are q and v at the nodes; over each interval the closed
+  loop is simulated as `vmc.sim.rollout` does (the command held over each of `substeps` control
+  steps, the robot advanced by the linearly implicit step or by `"rk4"`), and constraints join
+  the end of an interval to the next node. A plan is the closed loop of a simulation at that
+  control step (a test reproduces `rollout` to rounding error), and agrees with `Collocation` as
+  the control step shrinks (first order). The start is the pair of Params `shooting.q0` and
+  `shooting.v0`, which a problem can declare as parameters. `steps` names live Params that take
+  one value in every interval, between their bounds: trajectories of stiffness and references,
+  returned in `Result.steps` (`apply(target, interval=k)` sets the values of interval k). The
+  model does not carry the force that balances the robot at q0 under `initial`, as `Collocation`
+  does.
+- `optimization.TankBudget(level, refill=True)`: the planned changes of the Params that step stay
+  within the energy of a `vmc.control.Tank`. The plan keeps the tank's level from the exact jump
+  of the controller's energy at each change, and from the energy the controller's dampers take
+  back, and keeps it at least zero; a test runs the plan through a real `Tank` and finds its level
+  to rounding error. The tank's capacity is not planned.
+- `optimization.MPC(problem, shift=1, rti=False)`: the plan as a receding-horizon controller. The
+  program is built once, with the measured state, the controller's Params now, the tank's level
+  and the references as parameters of each solve. `step(controller, q, v, references, latency=)`
+  solves from the measured state, starting from the previous plan moved up by `shift` intervals,
+  and applies the plan's Params through `controller.set` (so a `Tank` bounds them), returning
+  the energy jump as the adaptation laws do. A plan that took `latency` seconds (the measured
+  solve time by default) is applied as of that time. With `rti`, one SQP iteration per step.
+  `start` and `poll` plan in a thread and apply the plan once it is ready, as of the time since
+  the start (CasADi lets other threads run during a solve; the solver is created with the `MPC`,
+  as it is not safe to create one in a second thread). `Problem.warm_up()` builds the program and
+  the solver now, and `Problem.solve` attaches the iteration callback only when it is given a
+  `progress`.
+- Planning with virtual states: `Collocation`, `Shooting` and `Equilibrium` accept controllers
+  with virtual states (a flywheel, a mass the robot is tied to). The states are unknowns of the
+  plan at every node, with the controller's own dynamics: collocated with the same scheme as the
+  robot (`Collocation`), or advanced as `VMCController.step` and `vmc.sim.rollout` advance them
+  (`Shooting`, which then reproduces `rollout` to rounding error, the states included). They
+  start from the state the controller is compiled with, or from `z0` (positions, then
+  velocities); a periodic motion repeats them; `Equilibrium` rests them. `Result.z` holds them,
+  `warm_start` takes them, `TankBudget` reads the energy at them, and the controller in place
+  (`initial`) may have states too, as a system (it starts with the plan) or as a running
+  controller (its state is where it is now). `MPC` plans a running controller from
+  `controller.z` when the `Shooting` has a `z0`, which is then a parameter of the program
+  (`shooting.z0`). The docstring of `Shooting` now says what the code does: the controller is
+  called at every one of an interval's `substeps` control steps.
+- Sensors of combinations of the coordinates: `Measurement(..., matrix=)` takes an (m, n) matrix
+  and reads `matrix @ q` and `matrix @ v` (instead of `observed`, a selection of coordinates).
+  `KalmanFilter.encoder` of a robot with fewer motors than coordinates (`Underactuated`) no longer
+  reads the motors as if they gave `q`, with the passive coordinates frozen: it returns the
+  measurement of the motors themselves, with the Jacobian of the motor angles at the estimate as
+  the matrix, so the passive coordinates are left to the model (`Rq` and `Rv` are then the
+  covariances of the motors' readings). A robot with a motor on every coordinate keeps its encoder
+  as it was. The underactuated tutorial runs the naive controller on such an estimate, and shows
+  what it takes: a process noise that admits the model's error (with the default one the gate
+  throws out every reading after the first swing and the filter breaks) and a controller that
+  does not outrun the filter.
+- Equations of motion from a function: `models.Equations(residual, energy=None)`, given to
+  `FunctionModel(..., equations=)`, for a black-box, learned or external model whose dynamics
+  are not built from parts. The residual `r(q, v, a, tau, f, p) = M(q) a + h(q, v) - tau - f` is
+  written with CasADi operations and affine in `a`; `tau` is the generalized force of the motors
+  and `f` that of the robot's own components, which still add springs, dampers and contact (the
+  masses and the weight are in the equations, so there is no `Inertance` or `Gravity`).
+  Everything that runs on a robot runs on it: the simulator, `rollout`, the planners, the
+  Kalman filter, the momentum observer. With an `energy(q, v, p)` returning (T, V) it has the
+  robot's energy and power; without one `Dynamics.energy` and `power` are `None` and what needs
+  them (`ModelPlant.energy`, the `Passivation` stage) raises a `ValueError` that says so
+  (`dynamics.needs_energy`). `testing.check_model` checks such a robot's mass matrix
+  (symmetric, positive) and, with an energy, that a simulation never gains any. A test builds
+  the same two-link arm from parts and from textbook equations and finds the same dynamics,
+  energy, simulation, Kalman prediction and plan.
+- Plan a controller on some coordinates of a larger robot: `Problem(system, plant=robot)` takes
+  the dynamics from `plant` (every term and `q0` in its coordinates) while the controller stays
+  written for its own robot, and reads the plant's motors as `VMCController` does in a
+  simulation, through its transmission. The law, the energy of a `TankBudget` and the dampers'
+  power of a shooting all go through it. A shooting of the turtle's flywheel controller on
+  `turtle.crawler()` equals the simulation step for step, the flywheel's states included (a
+  test), and the tutorial "Crawl with a flywheel" plans a stride with it. `Shooting(running=)`
+  says whether a controller started from `z0` is already running (`z0` alone still means so)
+  or starts with the plan, as one reset there does. `Space.on_manifold(q)` gives the equations
+  that a configuration obeys (the unit norm of a quaternion; none for a flat space), and
+  `Shooting` and `Equilibrium` constrain their nodes with them: before, a plan of a floating body
+  could drift off unit quaternions and plan another body's motion.
+- The models as numpy and PyTorch code: `core.backends.source`, `translate` and `export` write
+  a CasADi function as straight-line Python, one statement per operation of its expression
+  graph, for numpy (the text imports numpy only, so it runs without CasADi) or PyTorch
+  (differentiable, on any dtype and device). Arguments and results have CasADi's shapes, with any
+  leading batch dimensions. `Kinematics.functions(at, backend="numpy")`, `Dynamics.export` and
+  `Compiled.export` give a model's functions that way, each with its `source`. numpy gives
+  CasADi's numbers to rounding error and PyTorch to 1e-12 on the kinematics with their Jacobians
+  and Hessians, including the derivatives by autograd; a model with a poorly conditioned mass
+  matrix (the soft arm's dynamics) differs by a few parts in 1e11, as PyTorch's `sin` and `cos`
+  differ in the last place. The extra `virtualmodelcontrol[torch]` and the tutorial "Use a model
+  outside CasADi".
+- `ForceTracking`, `StiffnessTracking`, `PositionRegulation`, `HoldingGoals`, `ContactForce` and
+  `TaskStiffness` refuse a `StateController` (also inside a `Tank`) with a `ValueError` that says
+  so, instead of failing on the shapes of its inputs: they read a controller in the layout of the
+  motors. A robot with fewer motors than coordinates uses the plain frozen controller (it reads the
+  motors), or `control.underactuated.DirectionalForce` for a force.
+- Solver presets: `Problem(system, solver=...)` takes `"ipopt"` (the default), `"ipopt-exact"`
+  (exact Hessians: 40 iterations instead of 165 on the tutorial's shooting), `"sqp"` (CasADi's
+  `sqpmethod` with `qrqp`, the Hessian's negative eigenvalues clipped; other QP solvers by the
+  `qpsol` option), `"rti"` and `"fatrop"` (as a general problem, without stages).
+  `optimization.PRESETS` lists them and `optimization.solver.available(name)` tells whether the
+  CasADi build has the plugin. `Result.status` words FATROP's endings as IPOPT's.
+- Docs: tutorial "Model predictive control".
+- Docs: the page "Support policy": which versions of Python and numpy are supported, what
+  semantic versioning means here (a deprecation lasts at least one minor version), what the public
+  API is, the schema of the run logs, where to report an issue, and the safety checks before the
+  first run on a robot (also in "Real time and the robot").
+
+### Changed
+
+- `__all__` in `math`, `testing`, `compiler`, `dynamics` and `system`: what they list is the public
+  API, as in every other module; `from virtualmodelcontrol.x import *` gives only that.
+- The configuration and hardware profile files are read and written as UTF-8 on every platform,
+  so that a file written on Linux reads on Windows.
+- The docs use American spelling, the figure legends are 18 pt (readable on a phone), and wide
+  tables wrap their code on a narrow screen.
 
 ## [0.5.0] - 2026-10-06
 
@@ -13,6 +175,26 @@ tank, tuning and the calibrations), which was never released on its own.
 
 ### Added
 
+- Underactuated Virtual Model Control, for robots with fewer motors than coordinates.
+  `models.Underactuated(B)` is the actuation with an input matrix B (`Underactuated.joints` for
+  motors on some joints): motor angles Bᵀq, torques B u, the allocation B⁺ τ, the projector E and
+  the `defect` E τ it cannot realize. Its motors give the frozen configuration (the motors' part
+  of q, the rest at `q_rest`), so a `VMCController` on it is the frozen controller.
+  `control.StateController` reads (q, v) from the measurement (`meas["q"]`, `meas["v"]`, or its
+  `read`) instead of the motors, which is the naive controller and also how a controller acts
+  through an estimate of unmeasured coordinates. `control.underactuated` has `controller(compiled,
+  base="naive"|"frozen", correction=None|"passive"|"tank", gravity=)`, the `Passivation` output
+  stage (the passive and the tank correction: the motors never inject more power than the
+  robot's own dampers take, or more than the tank holds), `Frozen` (the frozen configuration,
+  also balancing the robot's gravity), `DirectionalForce` (a force along a direction by one
+  scalar of the stiffness, closed form, positive definite), `projector`, `defect` and `feasible`
+  (the wrenches the motors realize in full). An output stage with a `reset` is reset with its
+  controller. They agree with the lab's own code on its three robots (every flag, the frozen
+  point, the force law, and the closed loops).
+- `robots.planar`: `arm("three-link")` with one passive joint, `arm("five-link")` with three, and
+  `continuum()`, a three-section continuum arm driven by two tendons; `add_dynamics` and
+  `add_continuum_dynamics` give them gravity and their springs and dampers.
+- Docs: tutorial "Robots with fewer motors than joints".
 - `vmc.optimization`: plan the motion of a controller on a robot and optimize its Params.
   `Problem(system)` is built once and solved many times. `free` chooses the Params to optimize
   and `parameter` the ones set at every solve (references, say), by name or glob; bounds and

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: virtualmodelcontrol
-Version: 0.5.0
+Version: 1.1.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/
@@ -8,7 +8,7 @@ Author: Lorenzo Vignoli
 License-Expression: MIT
 License-File: LICENSE
 Keywords: casadi,control,passivity,robotics,soft robots,virtual model control
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
 Classifier: Operating System :: POSIX :: Linux
@@ -36,6 +36,8 @@ Provides-Extra: docs
 Requires-Dist: myst-nb>=1.1; extra == 'docs'
 Requires-Dist: sphinx-immaterial>=0.13; extra == 'docs'
 Requires-Dist: sphinx>=7.2; extra == 'docs'
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == 'torch'
 Description-Content-Type: text/markdown
 
 <a href="https://www.epfl.ch/labs/create/"><img align="right" height="72" src="https://raw.githubusercontent.com/vigno0405/VirtualModelControl/main/docs/_static/create-lab.png" alt="CREATE Lab, EPFL"></a>
@@ -72,8 +74,8 @@ Virtual environments, conda, ROS 2 and pinned versions are covered in [Installat
 
 ## Requirements
 
-Python 3.10 or newer, tested with 3.10 to 3.14 on Ubuntu 22.04 and 24.04. Nothing to compile;
-ROS and LaTeX are not needed.
+Python 3.10 or newer, tested with 3.10 to 3.14 on Ubuntu 22.04 and 24.04, and with the oldest
+versions of the packages below. Nothing to compile; ROS and LaTeX are not needed.
 
 ## Dependencies
 
@@ -87,6 +89,7 @@ pip installs them with the library:
 | [matplotlib](https://matplotlib.org) | 3.8 or newer | figures and animations |
 | [imageio-ffmpeg](https://github.com/imageio/imageio-ffmpeg) | 0.5 or newer | MP4 videos of the animations |
 | [PyYAML](https://pyyaml.org) | 6 or newer | robot and hardware files |
+| [PyTorch](https://pytorch.org) (optional, `pip install virtualmodelcontrol[torch]`) | 2.0 or newer | models as PyTorch code |
 
 ## The example in the figure
 

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/README.md

@@ -32,8 +32,8 @@ Virtual environments, conda, ROS 2 and pinned versions are covered in [Installat
 
 ## Requirements
 
-Python 3.10 or newer, tested with 3.10 to 3.14 on Ubuntu 22.04 and 24.04. Nothing to compile;
-ROS and LaTeX are not needed.
+Python 3.10 or newer, tested with 3.10 to 3.14 on Ubuntu 22.04 and 24.04, and with the oldest
+versions of the packages below. Nothing to compile; ROS and LaTeX are not needed.
 
 ## Dependencies
 
@@ -47,6 +47,7 @@ pip installs them with the library:
 | [matplotlib](https://matplotlib.org) | 3.8 or newer | figures and animations |
 | [imageio-ffmpeg](https://github.com/imageio/imageio-ffmpeg) | 0.5 or newer | MP4 videos of the animations |
 | [PyYAML](https://pyyaml.org) | 6 or newer | robot and hardware files |
+| [PyTorch](https://pytorch.org) (optional, `pip install virtualmodelcontrol[torch]`) | 2.0 or newer | models as PyTorch code |
 
 ## The example in the figure
 

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/docs/_static/custom.css

@@ -155,6 +155,20 @@ ul.contains-task-list {
   min-width: 14em;
 }
 
+/* On a phone a table has tighter cells and its code wraps, so a three-column table fits the
+   screen; a wider one still scrolls sideways inside itself. */
+@media screen and (max-width: 44.9375em) {
+  .md-typeset table.docutils.data:not(.plain) td,
+  .md-typeset table.docutils.data:not(.plain) th {
+    min-width: 0;
+    padding: 0.6em 0.5em;
+  }
+  .md-typeset table.docutils td code {
+    white-space: normal;
+    overflow-wrap: anywhere;
+  }
+}
+
 /* Display equations: a wide one scrolls sideways inside itself on a phone, not the page. */
 .md-typeset mjx-container[display="true"] {
   overflow-x: auto;

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/docs/concepts/conventions.md

@@ -20,7 +20,8 @@
 - Motor angles are `θ`, a generalized force is `τ`, actuator commands are `u`.
 - 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.
+- Arrays in, arrays out: inputs accept anything array-like; outputs are numpy arrays (torch
+  tensors from a model exported with `backend="torch"`).
 
 ## Continuum robots
 
@@ -60,7 +61,12 @@ site
   parameter `s`.
 
 plant
-  What the controller drives: a simulator such as `ModelPlant`, or the real robot.
+  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.
+
+tank
+  An energy budget for changing a running controller: a change is applied as far as the tank
+  pays for the energy it gives the controller, and what the controller's dampers take refills it.
 
 output stage
   An optional correction of the motor commands for real hardware: friction compensation,

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/docs/concepts/library.md

@@ -30,19 +30,22 @@ change, including that nothing in the library imports ROS.
 
 | You want to | Use |
 |---|---|
-| start from an existing robot | `virtualmodelcontrol.robots`: `helyx`, `bimanual`, `adapt`, `turtle`, `ur5` |
+| start from an existing robot | `virtualmodelcontrol.robots`: `helyx`, `bimanual`, `adapt`, `turtle`, `ur5`, `planar` |
 | 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 |
 | get positions, Jacobians, Hessians | `vmc.Kinematics` |
-| get the robot's equations of motion | `vmc.compile_dynamics` |
+| 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` |
+| estimate the state, forces and stiffness | `vmc.estimation`: `KalmanFilter`, `ContactForce`, `TaskStiffness` |
+| change a running controller's Params to track a goal | `vmc.adaptation`: `ForceTracking`, `StiffnessTracking`, `DitherSeeking` |
 | fit stiffness, damping and efficiencies to data | `vmc.identification` |
-| plan a motion and optimize a controller's Params | `vmc.optimization`: `Problem`, `Collocation`, `Effort`, `Cost`, `Bound` |
+| plan a motion and optimize a controller's Params | `vmc.optimization`: `Problem`, `Collocation`, `Shooting`, `MPC`, `Effort`, `Cost`, `Bound` |
 | record, save, replay and compare runs | `vmc.sim`: `RunLog`, `replay`, `compare` |
 | 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` |
 
 ## One symbolic source
@@ -60,4 +63,7 @@ $$
 
 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.
+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)).

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/docs/concepts/passivity.md

@@ -33,7 +33,7 @@ $$
 \dot E_c = -P + D + S .
 $$
 
-The compiled controller computes each term (`law.energy`, `law.power`), so the balance can be
+The compiled controller computes each term (`compiled.energy`, `compiled.power`), so the balance can be
 checked on any run.
 
 ## Passive controllers
@@ -73,7 +73,8 @@ weight.
   loop goes unstable even though every element is passive. [Tuning](../tutorials/tuning.md)
   shows the limit on damping.
 - **Changing parameters while running.** Raising a stiffness raises the energy stored in that
-  spring at once; `controller.set` returns that jump ([Parameters](../tutorials/parameters.md)).
+  spring at once; `controller.set` returns that jump ([Parameters](../tutorials/parameters.md)),
+  and a `Tank` pays for it ([Energy and passivity](../tutorials/energy.md)).
   Swapping elements through a smooth blend (`vmc.control.SwapController`) keeps the torques
   continuous.
 - **Sources.** A force source can supply any energy; only gravity compensation is tame.
@@ -81,5 +82,9 @@ weight.
   $\eta P$, and the balance holds with $\eta E_c$. Different efficiencies on motors that one
   element couples make its forces non-conservative, as the [finger example](../examples/finger.md)
   explains.
+- **Joints that no motor drives.** Torques that the motors alone can give, $B^+\tau$, are not
+  the gradient of a potential, so the controller may not be passive any more. [Robots with
+  fewer motors than joints](../tutorials/underactuated.md) shows the controllers that keep it
+  passive.
 - **Output stages.** Friction compensation, pretension and torque limits change the torques the
   motors receive, so the robot's input is no longer the controller's port.

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/docs/concepts/vmc.md

@@ -68,7 +68,10 @@ $$
 
 with $B$ the robot's actuation map. For a tendon arm $B = (\partial\theta/\partial q)^\top$,
 with $\theta$ the motor angles. With one motor per joint $B$ is the identity. The controller
-never divides $u$ by an [efficiency](efficiency.md).
+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.
 
 ## Virtual states
 

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/docs/development/contributing.md

@@ -25,17 +25,19 @@ cd VirtualModelControl
 .venv/bin/sphinx-build -W -b html docs docs/_build/html
 ```
 
-The site then opens from `docs/_build/html/index.html`.
+The site then opens from `docs/_build/html/index.html`. The tests of the PyTorch code skip
+themselves without PyTorch: install it with `pip install -e ".[torch]"` to run them.
 
 ## Code
 
 - SI units inside the library; degrees only in the hardware profiles.
 - No numbers in model code: every geometric or physical number is a `Param`, with its default
   in the robot's template, and templates take their geometry as arguments.
-- Models are written once, with CasADi operations; no second copy in numpy or sympy.
+- Models are written once, with CasADi operations; no second copy in numpy or sympy. The numpy
+  and PyTorch code of a model is generated from its graph (`core.backends`).
 - Docstrings are short (one to three lines, numpydoc, units on physical quantities); theory goes
   in the documentation.
-- New behaviour is opt-in: projects pin a version, and a finished experiment must run the same
+- New behavior is opt-in: projects pin a version, and a finished experiment must run the same
   after an update.
 - Every change adds a line to `CHANGELOG.md` under "Unreleased".
 
@@ -80,4 +82,5 @@ Versions follow semantic versioning and come from git tags. To release:
    ```
 
 The release workflow builds the package, publishes it to PyPI and creates the GitHub release.
+Check that the checks of the pushed commit have passed before you tag it.
 The documentation is rebuilt and published whenever a push to `main` changes it or the code.

virtualmodelcontrol-1.1.0/docs/development/support.md

@@ -0,0 +1,48 @@
+# Support policy
+
+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
+need, is tried with its newest release.
+
+A Python version is dropped, in a minor release and with a line in the
+[changelog](changelog.md), once it has reached the end of its life. The same goes for the
+oldest numpy, SciPy, CasADi and matplotlib that the library asks for.
+
+The tests also run on macOS and Windows, on request: they are not part of every push.
+
+## Versions of the library
+
+Versions follow [semantic versioning](https://semver.org). A minor or patch release does not
+break the public API, and a name that is going away warns with a `DeprecationWarning` for at
+least one minor release before a major release removes it.
+
+The public API is what the [reference](../api/index.md) lists: the names in the `__all__` of a
+module. Names that start with an underscore, and modules the reference does not list, are
+internal and may change at any time.
+
+A fix can change numbers. When it does, the changelog says so, with what changed and from
+which version, as it did for the arc formula of the soft arm's kinematics. An experiment that
+must run the same way always has to pin the version ([Installation](../installation.md)).
+
+Run logs carry the library's version and a version of their layout. A log of an older layout
+is read by newer versions, and a log of a newer layout is refused with a message that says to
+update. The changelog lists a change to the layout of the configuration files.
+
+## Safety
+
+The library gives no guarantee of safety on a real robot. Nothing limits a torque unless you add
+the output stage that does, and a controller that is passive in theory can still go unstable
+with the delay and the sampling of your loop. Read "Before the first run" in [Real-time
+runs](../tutorials/real-time.md) before the first run on a robot.
+
+## Problems
+
+Report a bug, or a page that does not work as written, on the
+[issue tracker](https://github.com/vigno0405/VirtualModelControl/issues), with the output of
+`pip show virtualmodelcontrol` and of `python -c "import casadi, numpy; print(casadi.__version__, numpy.__version__)"`.

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/docs/docs_setup.py

@@ -7,4 +7,5 @@ from virtualmodelcontrol import viz
 
 viz.use_style(usetex=False)  # Computer Modern without needing LaTeX on the build machine
 plt.rcParams["figure.figsize"] = (6.4, 4.4)  # [in]: 18 pt text stays readable on a phone
+plt.rcParams["legend.fontsize"] = 18  # and so do the legends, which the lab style makes smaller
 get_ipython().run_line_magic("config", "InlineBackend.figure_formats = ['svg']")

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/docs/examples/finger.md

@@ -50,7 +50,7 @@ params.table(adapt.finger(), {
     "m_mcp.mass": "mass of the proximal phalanx",
     "m_pip.mass": "mass of the middle phalanx",
     "m_dip.mass": "mass of the distal phalanx",
-    "dip_cog.position": "centre of gravity of the distal phalanx (also `mcp_cog`, `pip_cog`)",
+    "dip_cog.position": "center of gravity of the distal phalanx (also `mcp_cog`, `pip_cog`)",
     "gravity": "gravity in the finger's frame, as mounted",
 })
 ```

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/docs/examples/hand.md

@@ -77,7 +77,7 @@ The simulation leaves them out, for the reason given in the [finger example](fin
 
 A ball sits in front of the palm, in the robot mechanism. The simulator feels it, while the
 controller, compiled from its own components only, does not know it is there (see
-[contact](../tutorials/contact.md)). Springs pull three fingertips to the ball's centre.
+[contact](../tutorials/contact.md)). Springs pull three fingertips to the ball's center.
 
 The template's thumb tip, (0, 0, 0.0175) in its last joint frame like the fingers', is the point
 the hand's controllers attach to. It lies beside the thumb's last phalanx, which runs along
@@ -172,7 +172,7 @@ simulate. Its joint angles are only measured, and only the hand's torques are se
 ```{code-cell} python
 from virtualmodelcontrol.robots import ur5
 
-robot = ur5.with_hand()  # the hand centred on the flange, not turned
+robot = ur5.with_hand()  # the hand centered on the flange, not turned
 ctrl = vmc.Mechanism("ctrl")
 ctrl.add("gravity", vmc.GravityCompensation(robot))
 system = vmc.VirtualMechanismSystem(robot, ctrl)

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/docs/examples/hanging-arm.md

@@ -193,7 +193,7 @@ shows it little. On a real arm, add a run that keeps the motors moving.
 
 A tanh spring pulls the tip towards a target with at most 2 N, and a damper slows the tip
 down. An obstacle of radius 2 cm sits beside the arm's path, and the arm must keep 2 cm clear
-of it. Two Gaussian fields push the arm away from the obstacle's centre. They are attached at
+of it. Two Gaussian fields push the arm away from the obstacle's center. They are attached at
 $s = 0.6$ and at the tip, the ends of the part that has to get past the obstacle.
 
 ```{code-cell} python

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/docs/examples/soft-arm.md

@@ -52,6 +52,7 @@ from schematics import params
 
 arm = helyx.add_dynamics(helyx.arm("145-145-145"))
 glue("eta", 100 * helyx.EFFICIENCY, display=False)
+glue("pretension", helyx.PRETENSION_WEIGHTS, display=False)
 params.table(arm, {
     "seg1.L0": "rest length of segment 1 (also `seg2.L0`, `seg3.L0`)",
     "seg1.d": "distance of the tendons from the backbone",
@@ -74,8 +75,8 @@ matters for the forces the real arm exerts on its surroundings. The
 [efficiency page](../concepts/efficiency.md) explains when to use it.
 
 The nine motors and their bus are in `helyx.hardware("145-145-145")`. On the real arm,
-`helyx.output_stage()` adds a small pretension to every motor command (0.010 N·m per radian of
-motor angle). The simulations below leave it out.
+`helyx.output_stage()` adds a small pretension to every motor command
+({glue:text}`pretension:.3f` N·m per radian of motor angle). The simulations below leave it out.
 
 ## Reach past an obstacle
 

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/docs/index.md

@@ -108,7 +108,9 @@ tutorials/parameters
 tutorials/configurations
 tutorials/kinematics
 tutorials/build-a-robot
+tutorials/friction
 tutorials/extend
+tutorials/outside
 ```
 
 ```{toctree}
@@ -131,6 +133,7 @@ tutorials/contact
 tutorials/force
 tutorials/stiffness
 tutorials/energy
+tutorials/underactuated
 ```
 
 ```{toctree}
@@ -138,6 +141,7 @@ tutorials/energy
 :caption: Plan
 
 tutorials/optimize
+tutorials/mpc
 tutorials/crawl
 ```
 
@@ -173,5 +177,6 @@ concepts/conventions
 api/index
 development/changelog
 Roadmap <development/roadmap>
+development/support
 development/contributing
 ```

{virtualmodelcontrol-0.5.0 → virtualmodelcontrol-1.1.0}/docs/installation.md

@@ -120,10 +120,10 @@ pip install -e .
 An experiment should always run the same code. Pin the version, and move the pin on purpose:
 
 ```bash
-pip install "virtualmodelcontrol==0.1.0"
+pip install "virtualmodelcontrol==1.1.0"
 ```
 
-In a `requirements.txt` file, write `virtualmodelcontrol==0.1.0`. In a conda `environment.yml`,
+In a `requirements.txt` file, write `virtualmodelcontrol==1.1.0`. In a conda `environment.yml`,
 list it under `pip:`. `pip show virtualmodelcontrol` tells you which version you have, and the
 [changelog](development/changelog.md) what changed between versions.