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.

The robot and its controller are two separate mechanisms. The robot mechanism describes the hardware: its kinematics, its motors, its masses and, for simulation, its own stiffness and damping. The controller, a virtual mechanism, holds only the virtual elements we place on the robot. Here they are a spring from the tip to a goal and a damper on the tip; compile turns them into one fast function:

import virtualmodelcontrol as vmc
from virtualmodelcontrol.robots import helyx

arm = helyx.add_dynamics(helyx.arm("145-145-145"))  # the robot
goal = [0.15, 0.0, 0.35]  # [m]

ctrl = vmc.Mechanism("ctrl")  # the controller
ctrl.add("reach", vmc.LinearSpring(arm.point(s=1.0) - goal, 600.0))  # [N/m]
ctrl.add("damp", vmc.LinearDamper(arm.point(s=1.0), 5.0))  # [N·s/m]
ctrl.add("gravity", vmc.GravityCompensation(arm))

system = vmc.VirtualMechanismSystem(arm, ctrl)
controller = vmc.VMCController(vmc.compile(system))

The same controller runs on the hardware. Here it runs on a simulation built from the robot’s mechanism alone:

plant = vmc.sim.ModelPlant(arm)
log = vmc.sim.run(plant, controller, vmc.sim.SimClock(dt=1 / 330), T=3.0)
vmc.viz.animate(arm, log, "index-hero.mp4", springs=[(1.0, goal)],
                trace=1.0)

Install¶

pip install virtualmodelcontrol

Installation covers virtual environments, conda, ROS 2 and updates, and where to type the code of the pages.

Where to start¶

How it works explains the idea, and your first controller puts it to work on the soft arm. The tutorials then go through the library by topic, each a tab of the top bar: how to build a controller and a robot, how to run it, log it, tune it and estimate its state, how to control force and contact within an energy budget, and how to plan a motion. The examples apply it to complete tasks on ready-made robots:

• a soft arm that reaches past an obstacle and limits its force, and one that hangs from its base, identified from step responses;

• two soft arms that squeeze an object between them;

• a finger with a stiff fingertip and soft joint limits;

• a hand that grasps, alone or mounted on a UR5 arm;

• a crawling turtle whose two cranks follow a virtual flywheel.

The concepts explain the ideas behind the library: how it is organized, Virtual Model Control, passivity and the kinematics of the robots. The reference lists every function, the changelog and the roadmap.

Authors¶

virtualmodelcontrol is developed by Lorenzo Vignoli at the CREATE Lab of EPFL (Prof. Josie Hughes), in a collaboration with the University of Cambridge (Prof. Fulvio Forni). To cite it, use the CITATION.cff file of the repository.