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.

Install

pip install virtualmodelcontrol

The newest code, from GitHub, before it is released (the same line updates an existing install):

pip install --upgrade "git+https://github.com/vigno0405/VirtualModelControl.git"

Virtual environments, conda, ROS 2 and pinned versions are covered in Installation.

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:

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.

import numpy as np
import virtualmodelcontrol as vmc
from virtualmodelcontrol.robots import helyx

arm = helyx.arm("145-145-145")  # a soft arm with nine tendon motors
tip = arm.point(s=1.0)

ctrl = vmc.Mechanism("ctrl")
ctrl.add("reach", vmc.LinearSpring(tip - [0.15, 0.0, 0.35], 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 draws the figure from this run.

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: reach past an obstacle, and limit the force with a tanh spring.
• Hanging soft arm: identify its stiffness and damping, and reach around an obstacle.
• Two arms: squeeze an object between the tips of two soft arms.
• Finger: a stiff fingertip and soft joint limits.
• Hand: grasp a ball, alone or mounted on a UR5 arm.
• Turtle: two cranks that follow a virtual flywheel.

Documentation

The documentation holds the tutorials, the examples, the concepts and the API. What changed is in the changelog, what comes next in the roadmap, and how to contribute in Contributing.

Authors

Lorenzo Vignoli, at the CREATE Lab of EPFL (Prof. Josie Hughes), in a collaboration with the University of Cambridge (Prof. Fulvio Forni). To cite the library, see CITATION.cff. The code is under the MIT license.