A Modern Simulation Wrapper for Google DeepMind’s MuJoCo

⚠️ WARNING
This package is currently in its zero-release stage. Class methods and APIs may change without prior notice. Please review the documentation and changelog after each update to stay informed about any modifications.

Installation

Add -U flag to upgrade pre-existing library

PyPI Package

pip install mujoco-toolbox

GitHub Package

pip install git+https://github.com/MGross21/mujoco-toolbox.git@main

Adding to Project Dependencies

Click to Expand

Place the following in your requirements.txt or pyproject.toml file.

PyPI

Expect less frequent, stable releases.

mujoco-toolbox

Github

Expect frequent rolling releases.

git+https://github.com/MGross21/mujoco-toolbox.git@main#egg=mujoco-toolbox

Extra Packages

FFMPEG

Required for mediapy dependency

Windows

winget install ffmpeg
ffmpeg -version

Linux

Debian/Ubuntu

sudo apt update && sudo apt install ffmpeg
ffmpeg -version

Arch Linux

sudo pacman -Syu ffmpeg
ffmpeg -version

MacOS

Using Homebrew

brew install ffmpeg
ffmpeg -version

Using MacPorts

sudo port install ffmpeg
ffmpeg -version

Example Script

Bare minimum to run MuJoCo simulation and display result

import mujoco_toolbox as mjtb

mjtb.Simulation("path/to/your/xml").run(render=True).save()

Data Capture

run() records MjData fields at data_rate captures per second. Each field is an array of shape (captures, *field_shape).

import mujoco_toolbox as mjtb

sim = mjtb.Simulation("path/to/xml", duration=5, data_rate=100, capture={"time", "qpos", "xpos"}).run()
sim.captured_data["qpos"]  # (500, nq)
sim.body_data("arm", "xpos")  # (500, 3)

Omit capture to use mjtb.CAPTURE_PARAMETERS, or pass capture="all" to record every numeric field.

Controllers

Pre-Made Controllers

The following controllers are available out-of-the-box:

• sin
• cos
• step
• random
• real_time _{(recommended controller for digital twins)}

You can import them as follows:

import mujoco_toolbox.controllers as ctrl

Custom

def foo(model: MjModel, data: MjData,**kwargs):
    # Perform logic based on model/data objects
    # ie. PID Controller

Extra keyword arguments to Simulation are passed to the controller on every step:

mjtb.Simulation("path/to/xml", controller=mjtb.sin, amplitude=0.5, frequency=2).run()

Instantiating a Digital Twin

import mujoco_toolbox as mjtb
from mujoco_toolbox.controllers import real_time

with mjtb.Simulation("path/to/xml", controller=real_time) as digitaltwin:
    viewer = digitaltwin.launch(show_menu=False)  # Open the simulation window
    while not viewer.done():  # until the window is closed (or ESC/Q)
        with digitaltwin.data_lock:
            digitaltwin.controller(digitaltwin.model, digitaltwin.data, {"mjdata_kwargs": value})

See MjData objects here

File Support

XML / MJCF (Native)

import mujoco_toolbox as mjtb

mjtb.Simulation("path/to/xml").show()

URDF

import mujoco_toolbox as mjtb

mjtb.Simulation("path/to/urdf", meshdir="path/to/mesh/files").show()  # supports *.stl or *.obj

Merging Capabilities

Supports full <mujoco>...</mujoco> and <robot>...</robot> structure as well as complete sub-tree structures.

import mujoco_toolbox as mjtb

# Merges: XML & URDF Files, XML & URDF Strings, Sub Tree Structures
mjtb.Simulation("path/to/xml_1", string_xml_var, ..., "path/to/xml_n").show()

⚠️ WARNING
Duplicate sub-tree items with the same name will cause MuJoCo to throw a FatalError.