virtualmodelcontrol 0.1.0__py3-none-any.whl

virtualmodelcontrol/sim/run.py

@@ -0,0 +1,73 @@
+"""The run loop: one loop for simulated and real plants, with a guard and a recorder."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+
+from ..core.signals import Signals
+
+MEASUREMENTS = ("motor_position", "motor_velocity")
+
+
+@dataclass
+class SimClock:
+    """Simulated time: each step advances the plant by ``dt`` [s]."""
+
+    dt: float
+
+
+@dataclass
+class Guard:
+    """Sends zero torque when a measurement is missing, flagged invalid, NaN or Inf."""
+
+    required: tuple[str, ...] = MEASUREMENTS
+    trips: int = 0
+
+    def ok(self, meas: Signals) -> bool:
+        """True if every required measurement is valid."""
+        good = all(meas.is_valid(name) for name in self.required)
+        self.trips += not good
+        return good
+
+
+@dataclass
+class RunLog:
+    """Recorded signals of a run, one row per step; ``arrays`` stacks them."""
+
+    rows: dict[str, list[np.ndarray]] = field(default_factory=dict)
+
+    def append(self, **values: Any) -> None:
+        """Add one row of named values."""
+        for name, value in values.items():
+            self.rows.setdefault(name, []).append(np.atleast_1d(np.asarray(value, dtype=float)))
+
+    def arrays(self) -> dict[str, np.ndarray]:
+        """Each signal as an (n_steps, ...) array."""
+        return {name: np.array(rows) for name, rows in self.rows.items()}
+
+
+def run(
+    plant: Any, controller: Any, clock: SimClock, T: float, guard: Guard | None = None
+) -> RunLog:
+    """Run ``controller`` on a simulated ``plant`` for ``T`` [s]; returns the recorded run.
+
+    Each step reads the plant, asks the controller for a command (zero torque if the guard
+    trips), writes it and advances the plant by ``clock.dt``.
+    """
+    guard = Guard() if guard is None else guard
+    log = RunLog()
+    meas = plant.read()
+    controller.reset(plant.t, meas)
+    for _ in range(round(T / clock.dt)):
+        meas = plant.read()
+        if guard.ok(meas):
+            cmd = controller.step(plant.t, meas)
+        else:
+            cmd = Signals(plant.t, motor_torque=np.zeros_like(plant.u))
+        plant.write(cmd)
+        log.append(t=plant.t, motor_torque=cmd["motor_torque"], **{n: meas[n] for n in meas.names})
+        plant.advance(clock.dt)
+    return log

virtualmodelcontrol/system.py

@@ -0,0 +1,55 @@
+"""A robot and the virtual mechanism that controls it, as one system."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .core.params import ParamSet
+from .mechanisms.components.base import Component
+from .mechanisms.coordinates.joints import State
+from .mechanisms.mechanism import Mechanism
+from .models.actuation import Direct
+
+
+class VirtualMechanismSystem:
+    """A robot mechanism (with a kinematic model) and the virtual mechanism attached to it.
+
+    Params are named ``<mechanism>.<name>``; a Param shared by the robot and the controller keeps
+    the robot's name. ``couplings`` is an optional third mechanism, treated like the controller.
+    """
+
+    def __init__(
+        self, robot: Mechanism, virtual: Mechanism, couplings: Mechanism | None = None
+    ) -> None:
+        if robot.model is None:
+            raise ValueError(f"robot {robot.name!r} needs a kinematic model")
+        self.robot = robot
+        self.virtual = virtual
+        self.couplings = couplings
+        self.actuation: Any = robot.actuation if robot.actuation is not None else Direct()
+
+    @property
+    def controllers(self) -> list[Mechanism]:
+        """The virtual mechanism and the couplings, if any."""
+        return [m for m in (self.virtual, self.couplings) if m is not None]
+
+    @property
+    def params(self) -> ParamSet:
+        """Every Param of the system, robot first."""
+        ps = ParamSet()
+        for mechanism in (self.robot, *self.controllers):
+            ps.merge(mechanism.params, mechanism.name)
+        return ps
+
+    @property
+    def states(self) -> list[State]:
+        """Virtual degrees of freedom, in order."""
+        return [s for m in self.controllers for s in m.states.values()]
+
+    @property
+    def components(self) -> list[tuple[str, Component]]:
+        """Controller components as (``mechanism.name``, component)."""
+        return [(f"{m.name}.{n}", c) for m in self.controllers for n, c in m.components.items()]
+
+    def __repr__(self) -> str:
+        return f"VirtualMechanismSystem({self.robot.name!r}, {self.virtual.name!r})"

virtualmodelcontrol-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,49 @@
+virtualmodelcontrol/__init__.py,sha256=E0QJMB_Ku0DLj06SSBGgnXUImzGIstTgBXe3e6LHoGw,1505
+virtualmodelcontrol/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+virtualmodelcontrol/compiler.py,sha256=97qhVBamIvYBDAf2HxP9WR3GeGXsVkQFWGdsvExYNzo,5876
+virtualmodelcontrol/dynamics.py,sha256=YWplGRVqtyH4xKWNms9DcmHzhOs9_Ec4zwkmJ-fLDNM,5416
+virtualmodelcontrol/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+virtualmodelcontrol/system.py,sha256=gfcDmffB7xpUJphtw4Wr31M7kdjI-ruYIStRzPM8GRo,2083
+virtualmodelcontrol/control/__init__.py,sha256=NmW5vQN8UcJlhDW3V4fc37LZYSnJ6XyL7E82fUSEhls,135
+virtualmodelcontrol/control/controller.py,sha256=ZLh1xxjgeGQRctDcYNsG1Ku5YateKK_iolNsqC1wsfc,3128
+virtualmodelcontrol/core/__init__.py,sha256=qxsDqaGE_6I2De9AGzWxPCMuT2KzGuShVfizdu1HkGY,527
+virtualmodelcontrol/core/params.py,sha256=C5BqagsGLay-aSOEQqCGiuMvFVF0X0pCFu0k-YOgzWI,9108
+virtualmodelcontrol/core/registry.py,sha256=8IWfZJB1cGyygET-qqJsi_nH_BdiSiLtWqu9DeYlO68,1651
+virtualmodelcontrol/core/signals.py,sha256=5fT6iiOk4UBV2ZUoD1gGJMrCG8rTz6yMzc-RwOPTSd0,1617
+virtualmodelcontrol/core/space.py,sha256=xG59fXBoLkA1FHGCyvrPgWty98yCxhtLFOyj4Cvy0vk,5182
+virtualmodelcontrol/core/symbolic.py,sha256=FxWm6hGFNjD6X6rQSjUyI3dJaDMN2z-Bi6SXud-OgAE,2151
+virtualmodelcontrol/core/units.py,sha256=XJSY1_2toVh_rSPVcH2vUfPlEsf6LGTB-fpB-hd8xnc,1006
+virtualmodelcontrol/mechanisms/__init__.py,sha256=ooJV38z81RHdstT6zIbtT4kFl_VeNbIEwp_qZs0cRUU,1084
+virtualmodelcontrol/mechanisms/mechanism.py,sha256=KQ8WQWkN3UE-GVwPGeDTpL4s_CgEslAv_6uzKGxYrKM,3615
+virtualmodelcontrol/mechanisms/components/__init__.py,sha256=a5Fm56UFgVuhRrQgRLdE_X2KeBYNeAg8BFz_AxX_iHM,728
+virtualmodelcontrol/mechanisms/components/base.py,sha256=vq3irvmneUZf8uq_gFuI1uyDWhdayZlj-3JvLNY78J0,2590
+virtualmodelcontrol/mechanisms/components/dissipation.py,sha256=E0AH4T47wh6B0dUGfPS5mpDN_7LWI4nE6oL5Ouc9i44,1685
+virtualmodelcontrol/mechanisms/components/inertance.py,sha256=uTO8d25WTiclbIhynvyrqjQSJOt9f5TMxKe0uUenonc,1744
+virtualmodelcontrol/mechanisms/components/sources.py,sha256=-tU3o_pIG6BtH2nZyjAgwXkBwDLEfTrMQut8dRE5UjM,2309
+virtualmodelcontrol/mechanisms/components/storage.py,sha256=nAe76S8L_aZtDuB_pm2BATYo2o03Tusdu2epsl-n9SU,10300
+virtualmodelcontrol/mechanisms/coordinates/__init__.py,sha256=bTY7pyy9MRrol5A3EKJqh9Ra0xx532HzBCE4S7tBx4U,540
+virtualmodelcontrol/mechanisms/coordinates/base.py,sha256=81WIiLpE017YX5FeiC-pHnHUdKR5kU2oE4IN9BylMDY,3661
+virtualmodelcontrol/mechanisms/coordinates/frames.py,sha256=nGuLSAQowICJ_-uNx8H9krK3GXxYMKOHDRaPLir3NlU,2156
+virtualmodelcontrol/mechanisms/coordinates/joints.py,sha256=aCj7nXBppYNpPWLY6O4cXTVXOUskm7iPkR36m04bd_Q,1715
+virtualmodelcontrol/mechanisms/coordinates/ops.py,sha256=DpvbLbWAmddhKZpcio2gtO3cJcgtl2XIxkMZL7sudU4,4972
+virtualmodelcontrol/mechanisms/coordinates/references.py,sha256=KXiT3UVtznfqgHDfM8a0AnipTw_fg7nVVlodVM8eBw0,1305
+virtualmodelcontrol/models/__init__.py,sha256=A3_HwU2p5S5XuvwSaY--PRp6EJBeNmjV0tf70n1Gl7g,561
+virtualmodelcontrol/models/actuation.py,sha256=PDKRUmPZloD8mq2gDZzKg-lp7kPVvhPh4i4CNmadKEc,7171
+virtualmodelcontrol/models/assembly.py,sha256=QGmdDWcvUlpfC-uKaM-SCS-aal8GD-MhUNZRRK9Lb8A,6884
+virtualmodelcontrol/models/kinematic.py,sha256=oKgEpk9PAqYkyoCMdkJEVhptMqUVUa1-k2MohdS4jtk,1422
+virtualmodelcontrol/models/continuum/__init__.py,sha256=pkrNcvrQ93Ly86iS5lgNGN0r1c__N57aX0Uw9nDHKyM,97
+virtualmodelcontrol/models/continuum/pcc.py,sha256=V0HJJWz73p1BnSXQVCbczOAEdu1fyOmMfKyhdsr9wUE,4977
+virtualmodelcontrol/models/rigid/__init__.py,sha256=-THPuFfle_2vjeZe-nu2lG0xi31pztvBS2jQTkI6HEQ,133
+virtualmodelcontrol/models/rigid/couplings.py,sha256=E7BO8v5kLg2mC2QxekrLpklXakzJsNRbrYatMpRUO9E,2363
+virtualmodelcontrol/models/rigid/poe.py,sha256=VVWzcAcZF6fojeoNSk1SErGM8mTmUK_VL4EIvbhaL8o,3927
+virtualmodelcontrol/robots/__init__.py,sha256=tdOyxcvni3revezROiWDV8eqX9X2GR5gPd_a2Olkrco,136
+virtualmodelcontrol/robots/adapt.py,sha256=U0a11gV37xbW2Krn3XquAZ4fqUO_HaDO_S2by5nRpUY,3546
+virtualmodelcontrol/robots/helyx.py,sha256=fagNg8iEU3evxa9AiOjLDZFkvya3gE8eKx6HXO7eh8Q,3604
+virtualmodelcontrol/sim/__init__.py,sha256=khTS2enjoYrbXRfgrFTLLLVcgEwvqY9wO_ZvfWLIViI,291
+virtualmodelcontrol/sim/model_plant.py,sha256=y5P7XUjk5_mlUC5DA1gXf6DOMFYkAqM6ALIVls8CL00,2805
+virtualmodelcontrol/sim/plant.py,sha256=pG_e1Qn9ozAysSecMSHG9HgezRU1dyPXL49lM4kpnL4,1122
+virtualmodelcontrol/sim/run.py,sha256=t4L0_KCsNO931GZAKVp2H9Q9u4wtl6K2X-sC6xmWxpg,2285
+virtualmodelcontrol-0.1.0.dist-info/METADATA,sha256=fXt-VpyvUyPMxt4ruSrG2vM25Fqz5-bTZw7PRghpKws,2843
+virtualmodelcontrol-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+virtualmodelcontrol-0.1.0.dist-info/licenses/LICENSE,sha256=0stuzGeBCLbI3KFHplc0nCKgO67svcYW-vIMw3I3Isw,1072
+virtualmodelcontrol-0.1.0.dist-info/RECORD,,

virtualmodelcontrol-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

virtualmodelcontrol-0.1.0.dist-info/licenses/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.