/mujoco-py

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

Primary LanguagePythonOtherNOASSERTION

Status: Maintenance (expect bug fixes and minor updates)

mujoco-py Documentation Build Status

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.0 released on 10/1/2018.

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

  1. Obtain a 30-day free trial on the MuJoCo website or free license if you are a student. The license key will arrive in an email with your username and password.
  2. Download the MuJoCo version 2.0 binaries for Linux or OSX.
  3. Unzip the downloaded mujoco200 directory into ~/.mujoco/mujoco200, and place your license key (the mjkey.txt file from your email) at ~/.mujoco/mjkey.txt.

If you want to specify a nonstandard location for the key and package, use the env variables MUJOCO_PY_MJKEY_PATH and 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.1,>=2.0

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

$ pip3 install -U 'mujoco-py<2.1,>=2.0'
$ 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

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/mujoco200/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:

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