mujoco-py

MuJoCo is a physics engine for detailed, efficient rigid body simulations with contacts. mujoco-py allows using MuJoCo from Python 3.

2,857

815

2,857

423

View on GitHub

Top Related Projects

dm_control

3,775

Google DeepMind's software stack for physics-based simulation and Reinforcement Learning environments, using MuJoCo.

bullet3

12,540

Bullet Physics SDK: real-time collision detection and multi-physics simulation for VR, games, visual effects, robotics, machine learning etc.

mujoco

7,805

Multi-Joint dynamics with Contact. A general purpose physics simulator.

simbody

2,294

High-performance C++ multibody dynamics/physics library for simulating articulated biomechanical and mechanical systems like vehicles, robots, and the human skeleton.

Quick Overview

MuJoCo-py is a Python wrapper for the MuJoCo physics engine, designed to facilitate the development of reinforcement learning algorithms and robotics simulations. It provides a high-performance interface to MuJoCo, allowing users to create and interact with complex physical environments efficiently.

Pros

High-performance physics simulation for robotics and RL tasks
Seamless integration with Python, making it accessible for researchers and developers
Supports advanced features like contact dynamics and constraint resolution
Compatible with popular RL libraries like OpenAI Gym

Cons

Requires a separate MuJoCo license (though free for personal and research use)
Installation can be complex, especially on certain operating systems
Limited documentation compared to some other physics engines
May have a steeper learning curve for beginners in physics simulation

Code Examples

Creating a simple environment and running a simulation:

import mujoco_py
import os

model = mujoco_py.load_model_from_path("path/to/your/model.xml")
sim = mujoco_py.MjSim(model)

for _ in range(1000):
    sim.step()
    if _ % 100 == 0:
        print(f"Simulation step: {_}")

Rendering the simulation:

viewer = mujoco_py.MjViewer(sim)
for _ in range(1000):
    sim.step()
    viewer.render()

Applying control inputs:

while True:
    sim.data.ctrl[:] = [1.0, -1.0]  # Example control input
    sim.step()
    viewer.render()

Getting Started

Install MuJoCo (version 2.1 or later) from the official website.
Set the MUJOCO_PY_MUJOCO_PATH environment variable to your MuJoCo installation directory.
Install mujoco-py:

pip install mujoco-py

Create a simple Python script to test the installation:

import mujoco_py
import os

mj_path = mujoco_py.utils.discover_mujoco()
xml_path = os.path.join(mj_path, 'model', 'humanoid.xml')
model = mujoco_py.load_model_from_path(xml_path)
sim = mujoco_py.MjSim(model)

print(sim.data.qpos)

Run the script to confirm that mujoco-py is working correctly.

Competitor Comparisons

dm_control

3,775

Google DeepMind's software stack for physics-based simulation and Reinforcement Learning environments, using MuJoCo.

Pros of dm_control

More comprehensive and flexible control suite for reinforcement learning
Better integration with DeepMind's machine learning ecosystem
Improved visualization and rendering capabilities

Cons of dm_control

Steeper learning curve for beginners
Less widespread adoption in the research community
May require more computational resources for complex simulations

Code Comparison

dm_control:

from dm_control import suite
env = suite.load(domain_name="cartpole", task_name="swingup")
timestep = env.reset()
action = env.action_spec().generate_value()
next_timestep = env.step(action)

mujoco-py:

import mujoco_py
import os
model = mujoco_py.load_model_from_path("cartpole.xml")
sim = mujoco_py.MjSim(model)
sim.step()

Both libraries provide Python bindings for MuJoCo physics engine, but dm_control offers a more structured approach with its suite of environments and tasks. mujoco-py provides a lower-level interface, giving users more direct control over the simulation. dm_control's code is more abstracted, making it easier to set up and run experiments, while mujoco-py requires more manual configuration but offers greater flexibility for custom environments.

bullet3

12,540

Bullet Physics SDK: real-time collision detection and multi-physics simulation for VR, games, visual effects, robotics, machine learning etc.

Pros of bullet3

Open-source and free to use, unlike MuJoCo which requires a license
Wider range of supported platforms, including mobile devices
More extensive documentation and community support

Cons of bullet3

Generally slower performance compared to MuJoCo-py
Less accurate physics simulation in some scenarios
Steeper learning curve for beginners

Code Comparison

bullet3:

import pybullet as p
import pybullet_data

physicsClient = p.connect(p.GUI)
p.setAdditionalSearchPath(pybullet_data.getDataPath())
p.setGravity(0, 0, -9.81)
planeId = p.loadURDF("plane.urdf")

MuJoCo-py:

import mujoco_py
import os

model = mujoco_py.load_model_from_path("model.xml")
sim = mujoco_py.MjSim(model)
viewer = mujoco_py.MjViewer(sim)
sim.step()

Both libraries offer Python bindings for physics simulations, but bullet3 uses a more explicit initialization process, while MuJoCo-py relies on XML model files for setup. bullet3 provides more flexibility in terms of environment configuration, while MuJoCo-py offers a more streamlined approach for certain robotics applications.

mujoco

7,805

Multi-Joint dynamics with Contact. A general purpose physics simulator.

Pros of mujoco

More actively maintained and updated
Better integration with DeepMind's reinforcement learning libraries
Improved performance and stability

Cons of mujoco

Less established ecosystem and community support
Potential compatibility issues with existing projects using mujoco-py
Steeper learning curve for users familiar with mujoco-py

Code Comparison

mujoco:

import mujoco
model = mujoco.load_model_from_path("model.xml")
data = mujoco.MjData(model)
mujoco.mj_step(model, data)

mujoco-py:

import mujoco_py
model = mujoco_py.load_model_from_path("model.xml")
sim = mujoco_py.MjSim(model)
sim.step()

The code structure is similar, but mujoco uses a separate data object and explicit mj_step function, while mujoco-py combines these into a MjSim object with a step method. This reflects the different approaches to API design between the two libraries.

simbody

2,294

High-performance C++ multibody dynamics/physics library for simulating articulated biomechanical and mechanical systems like vehicles, robots, and the human skeleton.

Pros of Simbody

Open-source and free to use, without licensing restrictions
More comprehensive physics simulation capabilities, including advanced biomechanics
Larger and more active community for support and contributions

Cons of Simbody

Steeper learning curve due to more complex API and features
Less focus on robotics and reinforcement learning compared to MuJoCo-py
May require more computational resources for advanced simulations

Code Comparison

MuJoCo-py example:

import mujoco_py
model = mujoco_py.load_model_from_path("model.xml")
sim = mujoco_py.MjSim(model)
sim.step()

Simbody example:

#include <SimTK.h>
using namespace SimTK;
MultibodySystem system;
SimbodyMatterSubsystem matter(system);
GeneralForceSubsystem forces(system);
system.realizeTopology();
State state = system.getDefaultState();

Both libraries provide physics simulation capabilities, but Simbody offers a more comprehensive set of features for advanced biomechanics and general-purpose physics simulations. MuJoCo-py is more focused on robotics and reinforcement learning applications, with a simpler API that may be easier for beginners to grasp. The choice between the two depends on the specific requirements of your project and your familiarity with physics simulation concepts.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Status: Deprecated

`mujoco-py` does not support versions of MuJoCo after 2.1.0.

New users should depend on the official MuJoCo Python bindings.

mujoco-py

MuJoCo is a physics engine for detailed, efficient rigid body simulations with contacts. mujoco-py allows using MuJoCo from Python 3.

This library has been updated to be compatible with MuJoCo version 2.1 released on 2021-10-18.

Synopsis

Requirements

The following platforms are currently supported:

Linux with Python 3.6+. See the Dockerfile for the canonical list of system dependencies.
OS X with Python 3.6+.

The following platforms are DEPRECATED and unsupported:

Windows support has been DEPRECATED and removed in 2.0.2.0. One known good past version is 1.50.1.68.
Python 2 has been DEPRECATED and removed in 1.50.1.0. Python 2 users can stay on the 0.5 branch. The latest release there is 0.5.7 which can be installed with pip install mujoco-py==0.5.7.

Install MuJoCo

Download the MuJoCo version 2.1 binaries for Linux or OSX.
Extract the downloaded mujoco210 directory into ~/.mujoco/mujoco210.

If you want to specify a nonstandard location for the package, use the env variable MUJOCO_PY_MUJOCO_PATH.

Install and use `mujoco-py`

To include mujoco-py in your own package, add it to your requirements like so:

mujoco-py<2.2,>=2.1

To play with mujoco-py interactively, follow these steps:

$ pip3 install -U 'mujoco-py<2.2,>=2.1'
$ python3
import mujoco_py
import os
mj_path = mujoco_py.utils.discover_mujoco()
xml_path = os.path.join(mj_path, 'model', 'humanoid.xml')
model = mujoco_py.load_model_from_path(xml_path)
sim = mujoco_py.MjSim(model)

print(sim.data.qpos)
# [0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0.]

sim.step()
print(sim.data.qpos)
# [-2.09531783e-19  2.72130735e-05  6.14480786e-22 -3.45474715e-06
#   7.42993721e-06 -1.40711141e-04 -3.04253586e-04 -2.07559344e-04
#   8.50646247e-05 -3.45474715e-06  7.42993721e-06 -1.40711141e-04
#  -3.04253586e-04 -2.07559344e-04 -8.50646247e-05  1.11317030e-04
#  -7.03465386e-05 -2.22862221e-05 -1.11317030e-04  7.03465386e-05
#  -2.22862221e-05]

See the full documentation for advanced usage.

Troubleshooting

You're on MacOS and you see `clang: error: unsupported option '-fopenmp'`

If this happend during installation or just running python -c "import mujoco_py" then the issue seems to be related to this and the TL;DR is that for macOS the default compiler Apple clang LLVM does not support openmp. So you can try to install another clang/llvm installation. For example (requires brew):

brew install llvm
brew install boost
brew install hdf5

# Add this to your .bashrc/.zshrc:
export PATH="/usr/local/opt/llvm/bin:$PATH"

export CC="/usr/local/opt/llvm/bin/clang"
export CXX="/usr/local/opt/llvm/bin/clang++"
export CXX11="/usr/local/opt/llvm/bin/clang++"
export CXX14="/usr/local/opt/llvm/bin/clang++"
export CXX17="/usr/local/opt/llvm/bin/clang++"
export CXX1X="/usr/local/opt/llvm/bin/clang++"

export LDFLAGS="-L/usr/local/opt/llvm/lib"
export CPPFLAGS="-I/usr/local/opt/llvm/include"

Note: Don't forget to source your .bashrc/.zshrc after editing it and try to install mujoco-py again:

# Make sure your python environment is activated
pip install -U 'mujoco-py<2.2,>=2.1'

Missing GLFW

A common error when installing is:

raise ImportError("Failed to load GLFW3 shared library.")

Which happens when the glfw python package fails to find a GLFW dynamic library.

MuJoCo ships with its own copy of this library, which can be used during installation.

Add the path to the mujoco bin directory to your dynamic loader:

LD_LIBRARY_PATH=$HOME/.mujoco/mujoco210/bin pip install mujoco-py

This is particularly useful on Ubuntu 14.04, which does not have a GLFW package.

Ubuntu installtion troubleshooting

Because mujoco_py has compiled native code that needs to be linked to a supplied MuJoCo binary, it's installation on linux can be more challenging than pure Python source packages.

To install mujoco-py on Ubuntu, make sure you have the following libraries installed:

sudo apt install libosmesa6-dev libgl1-mesa-glx libglfw3

If you installed above libraries and you still see an error that -lGL cannot be found, most likely you need to create the symbolic link directly:

sudo ln -s /usr/lib/x86_64-linux-gnu/libGL.so.1 /usr/lib/x86_64-linux-gnu/libGL.so

Usage Examples

A number of examples demonstrating some advanced features of mujoco-py can be found in examples/. These include:

body_interaction.py: shows interactions between colliding bodies
disco_fetch.py: shows how TextureModder can be used to randomize object textures
internal_functions.py: shows how to call raw mujoco functions like mjv_room2model
markers_demo.py: shows how to add visualization-only geoms to the viewer
serialize_model.py: shows how to save and restore a model
setting_state.py: shows how to reset the simulation to a given state
tosser.py: shows a simple actuated object sorting robot application

See the full documentation for advanced usage.

Development

To run the provided unit and integrations tests:

make test

To test GPU-backed rendering, run:

make test_gpu

This is somewhat dependent on internal OpenAI infrastructure at the moment, but it should run if you change the Makefile parameters for your own setup.

Changelog

03/08/2018: We removed MjSimPool, because most of benefit one can get with multiple processes having single simulation.

Credits

mujoco-py is maintained by the OpenAI Robotics team. Contributors include:

Alex Ray
Bob McGrew
Jonas Schneider
Jonathan Ho
Peter Welinder
Wojciech Zaremba
Jerry Tworek

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of dm_control

Cons of dm_control

Code Comparison

Pros of bullet3

Cons of bullet3

Code Comparison

Pros of mujoco

Cons of mujoco

Code Comparison

Pros of Simbody

Cons of Simbody

Code Comparison

Convert designs to code with AI

README

mujoco-py does not support versions of MuJoCo after 2.1.0.

New users should depend on the official MuJoCo Python bindings.

mujoco-py

Synopsis

Requirements

Install MuJoCo

Install and use mujoco-py

Troubleshooting

You're on MacOS and you see clang: error: unsupported option '-fopenmp'

Missing GLFW

Ubuntu installtion troubleshooting

Usage Examples

Development

Changelog

Credits

Top Related Projects

Convert designs to code with AI

`mujoco-py` does not support versions of MuJoCo after 2.1.0.

Install and use `mujoco-py`

You're on MacOS and you see `clang: error: unsupported option '-fopenmp'`