virtualmodelcontrol 0.1.0__tar.gz → 0.2.0__tar.gz

{virtualmodelcontrol-0.1.0 → virtualmodelcontrol-0.2.0}/.gitignore

@@ -12,7 +12,6 @@ dist/
 src/virtualmodelcontrol/_version.py
 docs/_build/
 docs/jupyter_execute/
-docs/reference/generated/
 
 # Tool caches
 .pytest_cache/
@@ -22,3 +21,11 @@ docs/reference/generated/
 
 # Papers stay out of the repository
 *.pdf
+docs/api/generated/
+# Animations written by the docs build
+docs/**/*.mp4
+docs/**/*.gif
+docs/**/*.webp
+
+# Lock file written by editor tooling; the project pins nothing
+uv.lock

virtualmodelcontrol-0.2.0/CHANGELOG.md

@@ -0,0 +1,148 @@
+# Changelog
+
+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 still change between minor
+versions, with one minor version of deprecation before a removal).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-04
+
+### Added
+
+- Every dependency installs with the package: numpy, SciPy, CasADi, matplotlib, PyYAML, the
+  Dynamixel SDK and pyserial. CI runs on Ubuntu 22.04 and 24.04, with a clean-install job.
+- Robot templates: `robots.bimanual` (two Helyx arms on one frame, with their identified
+  stiffness and damping and the transmission efficiency 0.12), `robots.adapt.hand` (five digits,
+  13 motors, spread coupling, masses and joint limits), `robots.turtle` (two cranks and the
+  virtual-flywheel controller), `robots.ur5` (from DH parameters) and `ur5.with_hand()`.
+- Every template is parametric in its geometry, with today's values as defaults:
+  `helyx.arm(lengths=..., section_radius=..., spool_radius=..., tendon_angles=..., masses=...)`
+  for any number of segments; `bimanual.arms(lengths=..., tendon_angles=...,
+  base_positions=..., efficiency=...)`, each one for both arms or by arm;
+  `adapt.finger(link_lengths=..., link_masses=..., link_cogs=..., joint_axes=...,
+  motor_radius=..., pulley_radius=..., pip_transmission=...)` and `adapt.finger_coupling`;
+  `adapt.hand(...)` and `ur5.with_hand(...)`, which replace any entry of the hand's geometry
+  tables by key (`tip_offsets={"thumb": ...}`), with the hand's mounting position on the
+  flange; `ur5.arm(d=..., a=..., alpha=...)`; joint-limit springs with custom ranges; output
+  stages and `add_dynamics` sized to the arm.
+- `vmc.Kinematics`: positions, rotations, Jacobians, angular Jacobians and Hessians of any site,
+  from configuration or from motor angles.
+- `models.JointSpace` for robots described by their joints only; `SerialChain.from_dh` and site
+  rotations; `Assembly` parts mounted on another part's frame.
+- `TendonTransmission(efficiency=...)` and `Direct(efficiency=...)` (one value or one per
+  motor): the robot receives the commanded torque times the efficiency. `adapt.finger`,
+  `adapt.hand` and `ur5.with_hand` take `efficiency=...` and stay lossless by default: the
+  measured `adapt.MOTOR_EFFICIENCY` and `adapt.HAND_MOTOR_EFFICIENCY` are static calibrations for
+  force estimates, and unequal efficiencies on coupled motors make virtual elements
+  non-conservative in simulation.
+- `SpeedRegulator`: drives a virtual state at a commanded speed, with a ramp.
+- `control.output`, opt-in output stages for real hardware: `FrictionCompensation`,
+  `Pretension`, `TorqueOffset`, `TorqueLimit`; each template's own stage
+  (`helyx.output_stage()`, `bimanual.output_stage()`, `adapt.output_stage()`,
+  `adapt.hand_output_stage()`).
+- `vmc.viz`: the lab figure style (`use_style`, `save` as PDF and SVG) and drawing helpers
+  (`draw_robot`, `draw_spring`, `draw_damper`, `draw_frame`, `draw_force`, `draw_goal`,
+  `label_axes`). `vmc.viz` is available after `import virtualmodelcontrol as vmc` and loads
+  matplotlib only when first used.
+- `vmc.viz.animate`: an animation of a run (the robot, springs to fixed points, the path of a
+  site, anything else through a callback), saved as MP4, GIF or animated WebP. `imageio-ffmpeg`
+  is now a dependency, so MP4 works on every system.
+- `vmc.sim.run(..., z0=...)` starts the controller from a given virtual state, and the run log
+  records the virtual state `z` when the controller has one.
+- Contact as stiff one-sided springs: signed distances `PlaneDistance` and `SphereDistance`,
+  `ContactSpring` (optional smoothing for optimization) and `ContactDamper` (damps only in
+  contact); `adapt.add_dynamics` gives the finger and the hand their gravity for simulation.
+- Documentation rebuilt for students: the Material layout (sections as tabs, the pages of each
+  section in the left sidebar), large type, the library's logo and navy colours;
+  installation and troubleshooting; tutorials (how it works, a first controller, coordinates
+  and components, parameters, energy, kinematics, tuning, contact, building a robot, extending
+  the library); an example per robot (soft arm, two arms, finger, hand and the UR5, turtle), each
+  opening with its robot's schematic and parameters; concepts (the library's structure, soft-arm
+  kinematics, conventions and glossary). Every figure, schematic, table value and animation is
+  computed when the documentation builds.
+- `vmc.hardware.HardwareProfile`: the motors of a robot (bus ID, Dynamixel model, sign, mode,
+  motor constant, optional torque limit) in the library's motor order, with the bus settings;
+  conversions both ways between encoder ticks, raw velocities, goal currents and the published
+  degrees of a ROS driver and SI units, with commands clamped before the integer conversion so
+  they saturate instead of overflowing; saved and loaded as YAML. Each template has its
+  profile: `helyx.hardware()`, `bimanual.hardware()`, `adapt.finger_hardware()`,
+  `adapt.hand_hardware()`, `turtle.hardware()`.
+- `vmc.hardware.DynamixelPlant`: a robot's Dynamixel motors as a plant through the Dynamixel
+  SDK, without ROS. It sets a safe goal before each motor's torque goes on, takes the start
+  positions as zero, reads angles and smoothed rates, writes torques as clamped goal currents,
+  sends zero torque when commands stop (a watchdog), and on leaving (exceptions and Ctrl-C
+  included) sends zero torque and switches the torque motors off; held motors keep their
+  position. `hardware.home` drives the motors slowly to recorded home positions and refuses a
+  motor that lost a turn; `hardware.scan` finds the motors and their baud rate;
+  `hardware.FakeBus` stands in for the bus in tests and dry runs.
+- `vmc.sim.WallClock`: `vmc.sim.run` on real time, the loop of simulation unchanged. Each step
+  runs on the computer's clock with its measured time; a reading older than `stale` sends
+  zero torque; a late step starts the next one from now instead of catching up; the log
+  records each step's `dt`, and `log.info` the rate, the slowest step, the overruns and the
+  stale readings, with a warning when steps overran.
+- `virtualmodelcontrol.ros` (ROS 2, any distribution; rclpy and std_msgs, loaded only when
+  used): `RosPlant`, the robot behind the lab driver's topics (degrees, the bus order, raw
+  signs, torques kept within the range of the driver's goal current); `serve`, a digital twin
+  that publishes a simulated robot on the same topics, with a lockstep mode in which a run over
+  ROS repeats the simulator's; `LiveParams`, a controller's live Params as ROS parameters,
+  applied between steps.
+
+### Changed
+
+- The soft arm models the efficiency of its tendons: it receives η = 0.12 times the commanded
+  torque (`helyx.EFFICIENCY`), and `helyx.SIM_STIFFNESS` and `helyx.SIM_DAMPING` are the
+  identified, physical values. 0.1.0 divided them by 0.12 and delivered the full torque: the
+  same equilibria without gravity, but natural frequencies about 2.9 times too high and a sag
+  under gravity about 8 times too small. Controllers are unchanged and never divide their
+  torques by η, so the simulated arm receives η of every command, gravity compensation
+  included.
+- The figure style without LaTeX uses matplotlib's own Computer Modern font (`cmr10`) instead
+  of DejaVu Serif, with tick labels set as math. Figures made with LaTeX are unchanged.
+
+### Fixed
+
+- `RunLog` copies each row, so a signal updated in place (a controller's virtual state) is
+  recorded correctly at every step.
+- `bimanual.add_dynamics` takes the stiffness and damping of one arm (a dict by arm, arrays
+  included) and keeps the other arm's identified values.
+- `viz.draw_robot`: no joint markers along continuum arms mounted in an assembly; robots without
+  geometry (joint-space models) draw nothing instead of failing; serial chains end at their
+  `tool` site (the UR5 flange) as well as at a `tip`.
+
+## [0.1.0] - 2026-10-04
+
+First public release.
+
+### Added
+
+- Package scaffold: `pyproject.toml` (hatchling + hatch-vcs), tests, docs, CI workflows.
+- `core`: `Param` and `ParamSet` with scopes (fixed, design, episode, stage) and a `Binding` that
+  keeps live Params symbolic and folds the rest in; spaces `Euclidean`, `SO2`, `Product`;
+  symbolic helpers; `Signals`; a registry with plugin entry points; unit strings.
+- `mechanisms`: coordinates (`FramePoint`, `Joint`, `State`, `Ref`, `Difference`, `Slice`,
+  `Stack`, `Projection`, `Norm`, `Custom`), components (linear, tanh, Gaussian, sigmoid,
+  polynomial and limit springs; linear and tanh dampers; `PointMass`, `Inertance`; `ForceSource`,
+  `GravityCompensation`) and `Mechanism`. A tanh spring on a projection saturates at its maximum
+  force in every direction.
+- `models`: parametric `PCC` with n segments, `TendonTransmission` (θ > 0 pulls), `Direct`
+  drive, and `SerialChain` (product of exponentials).
+- `robots.helyx`: the three Helyx arm geometries with their default parameters.
+- `VirtualMechanismSystem`, `compile()` and `VMCController`: about 20 µs per control step for
+  three springs and three dampers on a three-segment arm (`benchmarks/tick.py`).
+- `compile_dynamics()`: robot dynamics assembled from the robot's components (canonical
+  residual, mass matrix, energy, power, linearly implicit Euler step); `Gravity` component.
+- `sim`: `Plant` and `SimPlant` protocols, `ModelPlant`, `run()` with a `Guard` (zero torque on
+  missing or non-finite readings) and a `RunLog`.
+- `models.Actuation` protocol; `helyx.add_dynamics` with the simulated arm's stiffness and
+  damping.
+- Docs: closed-loop simulation tutorial and an "Extend the library" how-to.
+- `models.LinearCoupling` (one motor driving several joints), `models.Assembly` (several models
+  mounted on one base) with `StackedActuation`; `FramePoint` accepts a part and an arc parameter.
+- `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.2.0...HEAD
+[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-0.2.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.5
+Name: virtualmodelcontrol
+Version: 0.2.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/
+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: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: casadi>=3.6
+Requires-Dist: dynamixel-sdk>=3.7
+Requires-Dist: imageio-ffmpeg>=0.5
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: numpy>=1.26
+Requires-Dist: pyserial>=3.5
+Requires-Dist: pyyaml>=6
+Requires-Dist: scipy>=1.11
+Provides-Extra: dev
+Requires-Dist: import-linter>=2.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+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'
+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>
+
+# VirtualModelControl
+
+`virtualmodelcontrol` is a Python library for Virtual Model Control. You build a controller by
+attaching virtual springs, dampers and masses to your robot, and the library turns them into
+motor torques at the control rate, in simulation and on the real robot.
+
+<p align="center">
+  <a href="https://vigno0405.github.io/VirtualModelControl/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vigno0405/VirtualModelControl/main/docs/_static/logo-light.svg"><img src="https://raw.githubusercontent.com/vigno0405/VirtualModelControl/main/docs/_static/logo.svg" height="64" align="middle" alt="virtualmodelcontrol logo"></picture></a>
+  &nbsp;
+  <a href="https://vigno0405.github.io/VirtualModelControl/"><img src="https://img.shields.io/badge/Documentation-tutorials%20%C2%B7%20examples%20%C2%B7%20API-3c5488?style=for-the-badge&labelColor=13294b" align="middle" alt="Documentation: tutorials, examples, API"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vigno0405/VirtualModelControl/main/docs/_static/readme-hero.svg" width="820" alt="A soft arm whose tip a virtual spring pulls towards a goal, and the distance from the tip to the goal over time">
+</p>
+
+## Install
+
+```bash
+pip install virtualmodelcontrol
+```
+
+The newest code, from GitHub, before it is released (the same line updates an existing install):
+
+```bash
+pip install --upgrade "git+https://github.com/vigno0405/VirtualModelControl.git"
+```
+
+Virtual environments, conda, ROS 2 and pinned versions are covered in [Installation][install].
+
+## 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.
+
+## Dependencies
+
+pip installs them with the library:
+
+| Package | Version | Used for |
+| --- | --- | --- |
+| [numpy](https://numpy.org) | 1.26 or newer, 2.x included | arrays |
+| [CasADi](https://web.casadi.org) | 3.6 or newer | the symbolic models, their derivatives and the compiled controllers |
+| [SciPy](https://scipy.org) | 1.11 or newer | rotations of chains built from DH tables |
+| [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 |
+| [Dynamixel SDK](https://github.com/ROBOTIS-GIT/DynamixelSDK) | 3.7 or newer | Dynamixel motors |
+| [pyserial](https://github.com/pyserial/pyserial) | 3.5 or newer | serial sensors |
+
+## The example in the figure
+
+The robot and the controller are two separate mechanisms: the robot mechanism describes the
+hardware, and the controller holds the virtual elements placed on it.
+
+```python
+import numpy as np
+import virtualmodelcontrol as vmc
+from virtualmodelcontrol.robots import helyx
+
+arm = helyx.arm("145-290-290")  # a soft arm with nine tendon motors
+tip = arm.point(s=1.0)
+
+ctrl = vmc.Mechanism("ctrl")
+ctrl.add("reach", vmc.LinearSpring(tip - [0.25, 0.0, 0.55], 600.0))  # [N/m]
+ctrl.add("damp", vmc.LinearDamper(tip, 5.0))  # [N·s/m]
+ctrl.add("gravity", vmc.GravityCompensation(arm))
+controller = vmc.VMCController(vmc.compile(vmc.VirtualMechanismSystem(arm, ctrl)))
+
+meas = vmc.Signals(0.0, motor_position=np.zeros(9), motor_velocity=np.zeros(9))
+torques = controller.step(0.0, meas)["motor_torque"]  # [N·m], one per motor
+```
+
+The same controller runs on a simulation built from the robot's own masses, stiffness and
+damping; [readme_figure.py][figure] draws the figure from this run.
+
+```python
+arm = helyx.add_dynamics(arm)
+plant = vmc.sim.ModelPlant(arm)
+log = vmc.sim.run(plant, controller, vmc.sim.SimClock(dt=1 / 330), T=3.0)
+```
+
+## Examples
+
+Each example builds a ready-made robot, controls it in simulation and animates the run:
+
+- [Soft arm][soft-arm]: reach a point, avoid an obstacle, shape the whole arm.
+- [Two arms][two-arms]: squeeze an object between the tips of two soft arms.
+- [Finger][finger]: a stiff fingertip and soft joint limits.
+- [Hand][hand]: grasp a ball, alone or mounted on a UR5 arm.
+- [Turtle][turtle]: two cranks that follow a virtual flywheel.
+
+## Documentation
+
+The [documentation][docs] holds the tutorials, the examples, the concepts and the API. What
+changed is in the [changelog][changelog], what comes next in the [roadmap][roadmap], and how to
+contribute in [Contributing][contributing].
+
+## Authors
+
+Lorenzo Vignoli, at the [CREATE Lab][lab] of EPFL (Prof. Josie Hughes), in a collaboration
+with the University of Cambridge (Prof. Fulvio Forni). To cite the library, see [CITATION.cff][cite].
+The code is under the [MIT license][license].
+
+[lab]: https://www.epfl.ch/labs/create/
+[install]: https://vigno0405.github.io/VirtualModelControl/installation.html
+[figure]: https://github.com/vigno0405/VirtualModelControl/blob/main/docs/scripts/readme_figure.py
+[soft-arm]: https://vigno0405.github.io/VirtualModelControl/examples/soft-arm.html
+[two-arms]: https://vigno0405.github.io/VirtualModelControl/examples/two-arms.html
+[finger]: https://vigno0405.github.io/VirtualModelControl/examples/finger.html
+[hand]: https://vigno0405.github.io/VirtualModelControl/examples/hand.html
+[turtle]: https://vigno0405.github.io/VirtualModelControl/examples/turtle.html
+[docs]: https://vigno0405.github.io/VirtualModelControl/
+[changelog]: https://vigno0405.github.io/VirtualModelControl/development/changelog.html
+[roadmap]: https://vigno0405.github.io/VirtualModelControl/development/roadmap.html
+[contributing]: https://vigno0405.github.io/VirtualModelControl/development/contributing.html
+[cite]: https://github.com/vigno0405/VirtualModelControl/blob/main/CITATION.cff
+[license]: https://github.com/vigno0405/VirtualModelControl/blob/main/LICENSE

virtualmodelcontrol-0.2.0/README.md

@@ -0,0 +1,120 @@
+<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>
+
+# VirtualModelControl
+
+`virtualmodelcontrol` is a Python library for Virtual Model Control. You build a controller by
+attaching virtual springs, dampers and masses to your robot, and the library turns them into
+motor torques at the control rate, in simulation and on the real robot.
+
+<p align="center">
+  <a href="https://vigno0405.github.io/VirtualModelControl/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vigno0405/VirtualModelControl/main/docs/_static/logo-light.svg"><img src="https://raw.githubusercontent.com/vigno0405/VirtualModelControl/main/docs/_static/logo.svg" height="64" align="middle" alt="virtualmodelcontrol logo"></picture></a>
+  &nbsp;
+  <a href="https://vigno0405.github.io/VirtualModelControl/"><img src="https://img.shields.io/badge/Documentation-tutorials%20%C2%B7%20examples%20%C2%B7%20API-3c5488?style=for-the-badge&labelColor=13294b" align="middle" alt="Documentation: tutorials, examples, API"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vigno0405/VirtualModelControl/main/docs/_static/readme-hero.svg" width="820" alt="A soft arm whose tip a virtual spring pulls towards a goal, and the distance from the tip to the goal over time">
+</p>
+
+## Install
+
+```bash
+pip install virtualmodelcontrol
+```
+
+The newest code, from GitHub, before it is released (the same line updates an existing install):
+
+```bash
+pip install --upgrade "git+https://github.com/vigno0405/VirtualModelControl.git"
+```
+
+Virtual environments, conda, ROS 2 and pinned versions are covered in [Installation][install].
+
+## 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.
+
+## Dependencies
+
+pip installs them with the library:
+
+| Package | Version | Used for |
+| --- | --- | --- |
+| [numpy](https://numpy.org) | 1.26 or newer, 2.x included | arrays |
+| [CasADi](https://web.casadi.org) | 3.6 or newer | the symbolic models, their derivatives and the compiled controllers |
+| [SciPy](https://scipy.org) | 1.11 or newer | rotations of chains built from DH tables |
+| [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 |
+| [Dynamixel SDK](https://github.com/ROBOTIS-GIT/DynamixelSDK) | 3.7 or newer | Dynamixel motors |
+| [pyserial](https://github.com/pyserial/pyserial) | 3.5 or newer | serial sensors |
+
+## The example in the figure
+
+The robot and the controller are two separate mechanisms: the robot mechanism describes the
+hardware, and the controller holds the virtual elements placed on it.
+
+```python
+import numpy as np
+import virtualmodelcontrol as vmc
+from virtualmodelcontrol.robots import helyx
+
+arm = helyx.arm("145-290-290")  # a soft arm with nine tendon motors
+tip = arm.point(s=1.0)
+
+ctrl = vmc.Mechanism("ctrl")
+ctrl.add("reach", vmc.LinearSpring(tip - [0.25, 0.0, 0.55], 600.0))  # [N/m]
+ctrl.add("damp", vmc.LinearDamper(tip, 5.0))  # [N·s/m]
+ctrl.add("gravity", vmc.GravityCompensation(arm))
+controller = vmc.VMCController(vmc.compile(vmc.VirtualMechanismSystem(arm, ctrl)))
+
+meas = vmc.Signals(0.0, motor_position=np.zeros(9), motor_velocity=np.zeros(9))
+torques = controller.step(0.0, meas)["motor_torque"]  # [N·m], one per motor
+```
+
+The same controller runs on a simulation built from the robot's own masses, stiffness and
+damping; [readme_figure.py][figure] draws the figure from this run.
+
+```python
+arm = helyx.add_dynamics(arm)
+plant = vmc.sim.ModelPlant(arm)
+log = vmc.sim.run(plant, controller, vmc.sim.SimClock(dt=1 / 330), T=3.0)
+```
+
+## Examples
+
+Each example builds a ready-made robot, controls it in simulation and animates the run:
+
+- [Soft arm][soft-arm]: reach a point, avoid an obstacle, shape the whole arm.
+- [Two arms][two-arms]: squeeze an object between the tips of two soft arms.
+- [Finger][finger]: a stiff fingertip and soft joint limits.
+- [Hand][hand]: grasp a ball, alone or mounted on a UR5 arm.
+- [Turtle][turtle]: two cranks that follow a virtual flywheel.
+
+## Documentation
+
+The [documentation][docs] holds the tutorials, the examples, the concepts and the API. What
+changed is in the [changelog][changelog], what comes next in the [roadmap][roadmap], and how to
+contribute in [Contributing][contributing].
+
+## Authors
+
+Lorenzo Vignoli, at the [CREATE Lab][lab] of EPFL (Prof. Josie Hughes), in a collaboration
+with the University of Cambridge (Prof. Fulvio Forni). To cite the library, see [CITATION.cff][cite].
+The code is under the [MIT license][license].
+
+[lab]: https://www.epfl.ch/labs/create/
+[install]: https://vigno0405.github.io/VirtualModelControl/installation.html
+[figure]: https://github.com/vigno0405/VirtualModelControl/blob/main/docs/scripts/readme_figure.py
+[soft-arm]: https://vigno0405.github.io/VirtualModelControl/examples/soft-arm.html
+[two-arms]: https://vigno0405.github.io/VirtualModelControl/examples/two-arms.html
+[finger]: https://vigno0405.github.io/VirtualModelControl/examples/finger.html
+[hand]: https://vigno0405.github.io/VirtualModelControl/examples/hand.html
+[turtle]: https://vigno0405.github.io/VirtualModelControl/examples/turtle.html
+[docs]: https://vigno0405.github.io/VirtualModelControl/
+[changelog]: https://vigno0405.github.io/VirtualModelControl/development/changelog.html
+[roadmap]: https://vigno0405.github.io/VirtualModelControl/development/roadmap.html
+[contributing]: https://vigno0405.github.io/VirtualModelControl/development/contributing.html
+[cite]: https://github.com/vigno0405/VirtualModelControl/blob/main/CITATION.cff
+[license]: https://github.com/vigno0405/VirtualModelControl/blob/main/LICENSE

virtualmodelcontrol-0.2.0/docs/_ext/video.py

@@ -0,0 +1,49 @@
+"""A ``video`` directive: embeds an MP4 that the page's own code wrote, looping and muted."""
+
+from __future__ import annotations
+
+import html
+from pathlib import Path
+from typing import ClassVar
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx.application import Sphinx
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+
+LIMIT = 2_000_000  # [bytes] per video, so pages stay light on a phone
+logger = logging.getLogger(__name__)
+
+
+class Video(SphinxDirective):
+    """``video <path>`` (relative to the page) with an optional ``:caption:``."""
+
+    required_arguments = 1
+    option_spec: ClassVar = {"caption": directives.unchanged}
+
+    def run(self) -> list[nodes.Node]:
+        rel, path = self.env.relfn2path(self.arguments[0], self.env.docname)
+        if not Path(path).is_file():
+            logger.warning(f"video not found: {path}", location=self.get_location())
+            return []
+        size = Path(path).stat().st_size
+        if size > LIMIT:
+            logger.warning(f"video over 2 MB ({size} bytes): {path}", location=self.get_location())
+        self.env.note_dependency(rel)
+        dest = self.env.dlfiles.add_file(self.env.docname, rel)
+        src = "../" * self.env.docname.count("/") + "_downloads/" + Path(dest).as_posix()
+        caption = self.options.get("caption")
+        figcaption = f"<figcaption>{html.escape(caption)}</figcaption>" if caption else ""
+        markup = (
+            '<figure class="video">'
+            f'<video src="{src}" controls autoplay muted loop playsinline preload="metadata">'
+            "</video>"
+            f"{figcaption}</figure>"
+        )
+        return [nodes.raw("", markup, format="html")]
+
+
+def setup(app: Sphinx) -> dict[str, bool]:
+    app.add_directive("video", Video)
+    return {"parallel_read_safe": True, "parallel_write_safe": True}

virtualmodelcontrol-0.2.0/docs/_static/custom.css

@@ -0,0 +1,171 @@
+/* Large type: about 17 px text, 19 px on wide screens (the theme's root size grows with the
+   window). Bold titles. */
+.md-typeset {
+  font-size: 0.85rem;
+}
+.md-typeset h1,
+.md-typeset h2 {
+  color: var(--md-default-fg-color);
+  font-weight: 700;
+}
+.md-typeset h3 {
+  font-weight: 600;
+}
+/* The page title links to the page already; its hidden permalink would wrap on phones. */
+.md-typeset h1 .headerlink {
+  display: none;
+}
+
+/* The library's logo in the header, large enough to read. */
+.md-header__button.md-logo img {
+  height: 2rem;
+}
+
+/* The lab's logo, on the right above the page outline, on every page (not in the phone menu,
+   which reuses the outline). */
+.md-sidebar--secondary .lab-logo {
+  display: inline-block;
+  margin: 0 0 1.2rem 0.6rem;
+}
+.md-sidebar--secondary .lab-logo img {
+  display: block;
+  height: 4rem;
+  width: auto;
+}
+.md-nav--primary .lab-logo {
+  display: none;
+}
+/* Narrow windows and phones have no right column: the logo sits at the right end of the
+   header instead, so it is always on screen. */
+@media screen and (max-width: 59.9375em) {
+  .md-header__inner::after {
+    content: "";
+    flex-shrink: 0;
+    width: 2rem;
+    height: 2rem;
+    margin: 0 0.2rem 0 0.4rem;
+    background: url("create-lab.png") center / contain no-repeat;
+  }
+}
+
+/* The layout fills wide windows. */
+.md-grid {
+  max-width: 68rem;
+}
+
+/* The home page belongs to no section: its sidebar lists all of them. */
+@media screen and (min-width: 76.25em) {
+  .md-nav--lifted > .md-nav__list:not(:has(> .md-nav__item--active)) > .md-nav__item {
+    display: block;
+  }
+}
+
+/* Code cells like the theme's code blocks: no coloured margin. */
+:root {
+  --mystnb-source-border-color: transparent;
+  --mystnb-source-margin-color: transparent;
+}
+
+/* Colours: a deep navy header on a cool, very light page; in dark mode, deep blues throughout.
+   Links in blue, the figures' red as the accent. */
+[data-md-color-primary="custom"] {
+  --md-primary-fg-color: #13294b;
+  --md-primary-fg-color--light: #1f3d6b;
+  --md-primary-fg-color--dark: #0b1b33;
+  --md-primary-bg-color: #ffffff;
+  --md-primary-bg-color--light: rgba(255, 255, 255, 0.72);
+}
+[data-md-color-accent="custom"] {
+  --md-accent-fg-color: #e64b35;
+  --md-accent-fg-color--transparent: rgba(230, 75, 53, 0.1);
+  --md-accent-bg-color: #ffffff;
+  --md-accent-bg-color--light: rgba(255, 255, 255, 0.72);
+}
+[data-md-color-scheme="default"] {
+  --md-default-bg-color: #f5f8fc;
+  --md-code-bg-color: #e9eff7;
+  --md-typeset-a-color: #2b5797;
+  --md-footer-bg-color: #13294b;
+  --md-footer-bg-color--dark: #0b1b33;
+}
+[data-md-color-scheme="slate"] {
+  --mystnb-source-border-color: transparent;
+  --md-hue: 216;
+  --md-default-bg-color: #0d1a2d;
+  --md-default-bg-color--light: rgba(13, 26, 45, 0.54);
+  --md-default-bg-color--lighter: rgba(13, 26, 45, 0.26);
+  --md-default-bg-color--lightest: rgba(13, 26, 45, 0.07);
+  --md-code-bg-color: #13243d;
+  --md-typeset-a-color: #8ab4f8;
+  --md-footer-bg-color: #08121f;
+  --md-footer-bg-color--dark: #050c16;
+}
+[data-md-color-scheme="slate"][data-md-color-primary="custom"] {
+  --md-primary-fg-color: #08121f;
+  --md-primary-fg-color--light: #12223a;
+  --md-primary-fg-color--dark: #050c16;
+}
+[data-md-color-scheme="slate"][data-md-color-accent="custom"] {
+  --md-accent-fg-color: #ff7b66;
+  --md-accent-fg-color--transparent: rgba(255, 123, 102, 0.12);
+}
+
+/* Animations written by the pages (the video directive), shown at their own size or smaller. */
+figure.video {
+  margin: 1.5em 0;
+  text-align: center;
+}
+figure.video video {
+  display: inline-block;
+  width: auto;
+  height: auto;
+  max-width: 100%;
+  border: 1px solid var(--md-default-fg-color--lightest);
+  border-radius: 0.2rem;
+}
+figure.video figcaption {
+  font-size: 0.85em;
+  color: var(--md-default-fg-color--light);
+  margin-top: 0.5em;
+}
+
+/* Figures: white background in dark mode too, never wider than the text. */
+.cell_output img {
+  max-width: 100%;
+  height: auto;
+  background: #fff;
+  border-radius: 0.2rem;
+}
+
+/* Task lists (the roadmap): the checkbox replaces the bullet. */
+ul.contains-task-list {
+  list-style: none;
+  padding-left: 0.25rem;
+}
+
+/* Reference tables: names on one line and a readable last column; on a phone a wide table
+   scrolls sideways inside itself instead of squeezing its columns. */
+.md-typeset table.docutils td code {
+  white-space: nowrap;
+  word-break: normal;
+  overflow-wrap: normal;
+}
+.md-typeset table.docutils td:last-child {
+  min-width: 14em;
+}
+
+/* Display equations: a wide one scrolls sideways inside itself on a phone, not the page. */
+.md-typeset mjx-container[display="true"] {
+  overflow-x: auto;
+  overflow-y: hidden;
+  max-width: 100%;
+}
+
+/* The general index: its two columns stack on a phone, and long module names wrap. */
+@media screen and (max-width: 44.9375em) {
+  table.genindextable td {
+    display: block;
+    width: auto !important;
+    overflow-wrap: anywhere;
+  }
+}