virtualmodelcontrol 0.1.0__tar.gz

virtualmodelcontrol-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Environments
+.venv/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Generated
+src/virtualmodelcontrol/_version.py
+docs/_build/
+docs/jupyter_execute/
+docs/reference/generated/
+
+# Tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.ipynb_checkpoints/
+
+# Papers stay out of the repository
+*.pdf

virtualmodelcontrol-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# 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.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.

virtualmodelcontrol-0.1.0/CITATION.cff

@@ -0,0 +1,17 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+version: 0.1.0
+date-released: "2026-10-04"
+title: "virtualmodelcontrol: Virtual Model Control for robots"
+authors:
+  - family-names: Vignoli
+    given-names: Lorenzo
+    affiliation: "EPFL"
+repository-code: "https://github.com/vigno0405/VirtualModelControl"
+license: MIT
+keywords:
+  - robotics
+  - virtual model control
+  - passivity
+  - soft robots

virtualmodelcontrol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lorenzo Vignoli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

virtualmodelcontrol-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: virtualmodelcontrol
+Version: 0.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/
+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: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: casadi>=3.6
+Requires-Dist: numpy>=1.26
+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: pydata-sphinx-theme>=0.15; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
+Requires-Dist: sphinx-design>=0.5; extra == 'docs'
+Requires-Dist: sphinx>=7.2; extra == 'docs'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.8; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# VirtualModelControl
+
+`virtualmodelcontrol` is a Python library for Virtual Model Control (VMC). Robots and
+controllers are described as mechanisms: coordinates plus springs, dampers, inertances and
+sources. One CasADi model serves the real-time controller, simulation and optimization.
+
+A collaboration between EPFL (Prof. Josie Hughes) and the University of Cambridge
+(Prof. Fulvio Forni).
+
+## Install
+
+Python ≥ 3.10 on Linux, macOS or Windows:
+
+```bash
+pip install virtualmodelcontrol
+```
+
+Then `import virtualmodelcontrol as vmc`. The latest development version installs with
+`pip install "git+https://github.com/vigno0405/VirtualModelControl.git"`.
+
+## Develop
+
+On Linux or macOS (Windows: see the install page in the docs):
+
+```bash
+git clone https://github.com/vigno0405/VirtualModelControl.git
+cd VirtualModelControl
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev,docs]"
+.venv/bin/python -m pytest
+```
+
+On Debian/Ubuntu, `python3 -m venv` needs the `python3-venv` package
+(`sudo apt install python3-venv`); a conda environment works too. If ROS 2 is sourced in your
+shell, prefix these commands with `env -u PYTHONPATH` so ROS's Python packages stay out of the
+environment.
+
+## Documentation
+
+https://vigno0405.github.io/VirtualModelControl/
+
+To build it locally: `sphinx-build docs docs/_build/html`, then open
+`docs/_build/html/index.html`.
+
+## Citing
+
+See `CITATION.cff`.

virtualmodelcontrol-0.1.0/README.md

@@ -0,0 +1,47 @@
+# VirtualModelControl
+
+`virtualmodelcontrol` is a Python library for Virtual Model Control (VMC). Robots and
+controllers are described as mechanisms: coordinates plus springs, dampers, inertances and
+sources. One CasADi model serves the real-time controller, simulation and optimization.
+
+A collaboration between EPFL (Prof. Josie Hughes) and the University of Cambridge
+(Prof. Fulvio Forni).
+
+## Install
+
+Python ≥ 3.10 on Linux, macOS or Windows:
+
+```bash
+pip install virtualmodelcontrol
+```
+
+Then `import virtualmodelcontrol as vmc`. The latest development version installs with
+`pip install "git+https://github.com/vigno0405/VirtualModelControl.git"`.
+
+## Develop
+
+On Linux or macOS (Windows: see the install page in the docs):
+
+```bash
+git clone https://github.com/vigno0405/VirtualModelControl.git
+cd VirtualModelControl
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev,docs]"
+.venv/bin/python -m pytest
+```
+
+On Debian/Ubuntu, `python3 -m venv` needs the `python3-venv` package
+(`sudo apt install python3-venv`); a conda environment works too. If ROS 2 is sourced in your
+shell, prefix these commands with `env -u PYTHONPATH` so ROS's Python packages stay out of the
+environment.
+
+## Documentation
+
+https://vigno0405.github.io/VirtualModelControl/
+
+To build it locally: `sphinx-build docs docs/_build/html`, then open
+`docs/_build/html/index.html`.
+
+## Citing
+
+See `CITATION.cff`.

virtualmodelcontrol-0.1.0/benchmarks/tick.py

@@ -0,0 +1,58 @@
+"""Per-tick cost of a compiled soft-arm controller: 3 springs + 3 dampers on the 145/290/290 arm.
+
+Run from the repository root: ``python benchmarks/tick.py``. Target: ≤ 30 µs per tick.
+"""
+
+import time
+
+import numpy as np
+
+import virtualmodelcontrol as vmc
+from virtualmodelcontrol.robots import helyx
+
+
+def build() -> vmc.Compiled:
+    """The benchmark controller, compiled."""
+    arm = helyx.arm("145-290-290")
+    ctrl = vmc.Mechanism("ctrl")
+    for i, s in enumerate((0.2, 0.6, 1.0)):
+        point = arm.point(s=s)
+        goal = vmc.Ref("goal", 3, value=[0.02, 0.0, 0.7 * s])
+        ctrl.add(f"k{i}", vmc.LinearSpring(point - goal, 50.0))
+        ctrl.add(f"c{i}", vmc.LinearDamper(point, 2.0))
+    return vmc.compile(vmc.VirtualMechanismSystem(arm, ctrl))
+
+
+def per_tick(step, inputs, n: int = 5000) -> float:
+    """Mean wall time of ``step(input)`` [µs] after a warm-up."""
+    for k in range(300):
+        step(inputs[k % len(inputs)])
+    t0 = time.perf_counter()
+    for k in range(n):
+        step(inputs[k % len(inputs)])
+    return (time.perf_counter() - t0) / n * 1e6
+
+
+def main() -> None:
+    """Print compile time and per-tick costs."""
+    t0 = time.perf_counter()
+    law = build()
+    build_ms = (time.perf_counter() - t0) * 1e3
+    rng = np.random.default_rng(0)
+    theta, theta_dot = rng.uniform(-0.3, 0.3, (200, 9)), rng.uniform(-1.0, 1.0, (200, 9))
+    x = [
+        np.concatenate([a, b, law.live_values(), [0.0]])
+        for a, b in zip(theta, theta_dot, strict=True)
+    ]
+    meas = [
+        vmc.Signals(0.0, motor_position=a, motor_velocity=b)
+        for a, b in zip(theta, theta_dot, strict=True)
+    ]
+    controller = vmc.VMCController(law)
+    print(f"compile          : {build_ms:6.1f} ms")
+    print(f"fast function    : {per_tick(lambda v: np.asarray(law.fast(v)), x):6.1f} µs/tick")
+    print(f"controller.step  : {per_tick(lambda m: controller.step(0.0, m), meas):6.1f} µs/tick")
+
+
+if __name__ == "__main__":
+    main()

virtualmodelcontrol-0.1.0/docs/_static/custom.css

@@ -0,0 +1,4 @@
+/* Long names (modules, classes) wrap instead of running off the page. */
+h1, h2, h3, .prev-next-title, .bd-sidenav a, .bd-breadcrumbs a, .autosummary td {
+  overflow-wrap: anywhere;
+}

virtualmodelcontrol-0.1.0/docs/_templates/autosummary/module.rst

@@ -0,0 +1,60 @@
+{{ name | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {%- if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+   {%- block functions %}
+   {%- if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+   {%- block classes %}
+   {%- if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+   {%- block exceptions %}
+   {%- if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+{%- block modules %}
+{%- if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{%- endblock %}

virtualmodelcontrol-0.1.0/docs/conf.py

@@ -0,0 +1,51 @@
+"""Sphinx configuration."""
+
+from importlib.metadata import version as _version
+
+project = "virtualmodelcontrol"
+author = "Lorenzo Vignoli"
+copyright = "2026, Lorenzo Vignoli"
+release = _version("virtualmodelcontrol")
+version = ".".join(release.split(".")[:2])
+
+extensions = [
+    "myst_nb",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx_copybutton",
+    "sphinx_design",
+]
+
+myst_enable_extensions = ["amsmath", "colon_fence", "deflist", "dollarmath"]
+myst_heading_anchors = 3
+
+# Every code cell in the docs runs at each build, and an error fails the build.
+nb_execution_mode = "force"
+nb_execution_raise_on_error = True
+nb_execution_timeout = 300
+
+autosummary_generate = True
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+}
+
+html_theme = "pydata_sphinx_theme"
+html_title = "virtualmodelcontrol"
+exclude_patterns = ["_build", "jupyter_execute"]
+
+html_theme_options = {"github_url": "https://github.com/vigno0405/VirtualModelControl"}
+html_copy_source = False
+html_show_sourcelink = False
+templates_path = ["_templates"]
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+add_module_names = False

virtualmodelcontrol-0.1.0/docs/development/architecture.md

@@ -0,0 +1,44 @@
+# Architecture
+
+## Vocabulary
+
+A **mechanism** is a set of coordinates plus components acting on them. Every component is one
+of four kinds:
+
+- **storage:** has an energy `V(y)`; springs, gravity, elastic structure
+- **dissipation:** dampers and friction
+- **inertance:** masses, inertias, inerters
+- **source:** metered forces and motions
+
+This holds for the physical robot and for the virtual mechanism that controls it. A closed loop
+is the union of both mechanisms, so the same objects simulate, optimize and control.
+
+## Layers
+
+A module imports only from layers below it. `import-linter` checks this in CI
+(`lint-imports`), using the contracts in `pyproject.toml`.
+
+| Layer | Packages | Role |
+|---|---|---|
+| L7 research | `codesign`, `learning` | optional extras |
+| L6 decide | `optim`, `adaptation` | optimization, online tuning |
+| L5 analyse | `estimation`, `identification`, `passivity` | |
+| L4 run | `sim` | plants, model simulator, run loop |
+| L3 control | `system`, `compiler`, `dynamics`, `control` | compiled controllers and robot dynamics |
+| L2 describe | `models` | kinematics, continuum, rigid, actuation |
+| L1 vocabulary | `mechanisms` | coordinates and components |
+| L0 core | `core`, `io` | parameters, spaces, symbolic helpers, signals, registry |
+| edges | `viz`, `hardware`, `ros`, `robots` | never imported by L0–L7 |
+
+Packages appear as their release lands; the table is the target.
+
+## Seams
+
+Protocols exist only where implementations are swapped: model ↔ compiler, runtime ↔ hardware,
+problem ↔ solver. Everything else is concrete classes.
+
+## Symbolic core
+
+All models are written once with CasADi symbols. The dynamics have one canonical form, the
+implicit residual `M(q) a + h(q, v) − B(q) u − Σ Jᵀ f = 0`, so simulation, collocation,
+estimation and identification share it.

virtualmodelcontrol-0.1.0/docs/development/contributing.md

@@ -0,0 +1,49 @@
+# Contributing
+
+## Set up
+
+Linux or macOS, from a clone of the repository:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev,docs]"
+```
+
+On Debian/Ubuntu, `python3 -m venv` needs the `python3-venv` package
+(`sudo apt install python3-venv`); a conda environment works too. If ROS 2 is sourced in your
+shell, prefix every command on this page with `env -u PYTHONPATH`.
+
+## Check your change
+
+Run these from the repository root before opening a pull request:
+
+```bash
+.venv/bin/python -m pytest
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
+.venv/bin/mypy
+.venv/bin/lint-imports
+.venv/bin/sphinx-build -W -b html docs docs/_build/html
+```
+
+`pre-commit run --all-files` runs the formatters and file checks in one go. It is not
+installed as a git hook.
+
+## Rules
+
+- **SI units** inside the library. Unit conversions belong in the hardware layers.
+- **No numbers in model code.** Geometry, gains, masses and calibration are `Param`s; their
+  defaults live in robot data.
+- **CasADi is the only symbolic source.** No second copy of a model in numpy or sympy.
+- **Short docstrings:** numpydoc, a 1–3 line summary, units on physical parameters. Theory goes
+  in the docs.
+- **Ported code** comes with a golden regression test: a small `.npz` fixture in `tests/data/`
+  generated from the original implementation, plus the property tests that apply.
+- **Behaviour changes are opt-in.** Projects pin library versions; deprecate for one minor
+  version before removing anything.
+- Add a line to `CHANGELOG.md` under "Unreleased".
+
+## Release
+
+Releases follow semantic versioning (0.x for now). The version comes from git tags: pushing a
+tag `vX.Y.Z` builds the package and creates a GitHub release.

virtualmodelcontrol-0.1.0/docs/getting-started/first-controller.md

@@ -0,0 +1,79 @@
+---
+file_format: mystnb
+kernelspec:
+  name: python3
+---
+
+# Your first controller
+
+This page builds a controller for the three-segment soft arm, evaluates its torques and changes
+a gain while it runs. Every cell runs when the documentation is built.
+
+## The robot
+
+A robot is a `Mechanism` with a kinematic model. The `helyx` module builds the soft arm: a
+piecewise-constant-curvature (PCC) model with three segments, three tendons per segment, a lumped
+mass per segment and the gravity vector of its mounting.
+
+```{code-cell} python
+import numpy as np
+import virtualmodelcontrol as vmc
+from virtualmodelcontrol.robots import helyx
+
+arm = helyx.arm("145-290-290")
+print(arm)
+print(list(arm.params)[:6], "...")
+```
+
+Every number is a `Param` with a unit and a scope, geometry included:
+
+```{code-cell} python
+arm.params["seg1.delta"]
+```
+
+## The controller
+
+The controller is a second mechanism. Its components act on coordinates of the robot: here a
+spring pulls the tip towards a goal, and a damper slows the middle of the arm.
+
+```{code-cell} python
+ctrl = vmc.Mechanism("ctrl")
+tip = arm.point(s=1.0)            # arc parameter s: 0 at the base, 1 at the tip
+middle = arm.point(s=0.5)
+ctrl.add("drag", vmc.LinearSpring(tip - vmc.Ref("goal", 3, value=[0.1, 0.0, 0.6]), 30.0))
+ctrl.add("damp", vmc.LinearDamper(middle, 1.5))
+ctrl.add("gravity", vmc.GravityCompensation(arm))
+```
+
+## Compile and run
+
+`compile` turns the robot and the controller into CasADi functions. Gains and goals (scope
+`stage`) stay live inputs; geometry and attachment points are folded in.
+
+```{code-cell} python
+law = vmc.compile(vmc.VirtualMechanismSystem(arm, ctrl))
+print(law.live)
+```
+
+The controller reads motor angles and rates and returns motor torques. Motor angles follow the
+library convention: θ > 0 pulls a tendon.
+
+```{code-cell} python
+controller = vmc.VMCController(law)
+meas = vmc.Signals(0.0, motor_position=np.zeros(9), motor_velocity=np.zeros(9))
+controller.step(0.0, meas)["motor_torque"].round(4)
+```
+
+## Change a gain while running
+
+`set` changes live Params at once and returns the jump of the controller's stored energy, which
+energy-based safety layers need.
+
+```{code-cell} python
+jump = controller.set({"ctrl.drag.stiffness": 60.0})
+print(f"energy jump: {jump:.3e} J")
+controller.step(0.003, meas)["motor_torque"].round(4)
+```
+
+Attachment points are frozen by default. To move one while running, compile with
+`runtime=["ctrl.drag.s"]` (glob patterns work, for example `"*.s"`).

virtualmodelcontrol-0.1.0/docs/getting-started/install.md

@@ -0,0 +1,50 @@
+# Install
+
+The library needs Python ≥ 3.10 and runs on Linux, macOS and Windows. Its core depends only
+on numpy, scipy and CasADi.
+
+## Into an existing environment
+
+```bash
+pip install virtualmodelcontrol
+```
+
+The latest development version, straight from GitHub:
+
+```bash
+pip install "git+https://github.com/vigno0405/VirtualModelControl.git"
+```
+
+## Into a new virtual environment
+
+Linux and macOS:
+
+```bash
+python3 -m venv ~/venvs/vmc
+~/venvs/vmc/bin/pip install virtualmodelcontrol
+~/venvs/vmc/bin/python -c "import virtualmodelcontrol as vmc; print(vmc.__version__)"
+```
+
+Windows (PowerShell):
+
+```powershell
+py -m venv $HOME\venvs\vmc
+& $HOME\venvs\vmc\Scripts\pip install virtualmodelcontrol
+& $HOME\venvs\vmc\Scripts\python -c "import virtualmodelcontrol as vmc; print(vmc.__version__)"
+```
+
+On Debian/Ubuntu, `python3 -m venv` needs the `python3-venv` package
+(`sudo apt install python3-venv`). A conda environment works the same way: create one with any
+Python ≥ 3.10, activate it and run `pip install virtualmodelcontrol`.
+
+## ROS 2
+
+The library never needs ROS. Its optional ROS 2 parts use only `rclpy` and `std_msgs`, so any
+ROS 2 distribution works. ROS comes from the system's ROS install, not from pip.
+
+When ROS is sourced in your shell, `PYTHONPATH` points at ROS's own Python packages. Keep them
+out of the library's environment for installs and tests:
+
+```bash
+env -u PYTHONPATH ~/venvs/vmc/bin/python -c "import virtualmodelcontrol"
+```