namikosaito / mujoco_mpc

Real-time behaviour synthesis with MuJoCo, using Predictive Control

MuJoCo MPC (MJPC) is an interactive application and software framework for real-time predictive control with MuJoCo, developed by Google DeepMind.

MJPC allows the user to easily author and solve complex robotics tasks, and currently supports multiple shooting-based planners. Derivative-based methods include iLQG and Gradient Descent, while derivative-free methods include a simple yet very competitive planner called Predictive Sampling.

• Overview
• Graphical User Interface
• Installation
  • macOS
  • Ubuntu
  • Build Issues
• Predictive Control
• Contributing
• Known Issues
• Citation
• Acknowledgments
• License and Disclaimer

Overview

To read the paper describing this software package, please see our preprint.

For a quick video overview of MJPC, click below.

For a longer talk at the MIT Robotics Seminar in December 2022 describing our results, click below.

A more recent, December 2023 talk at the IEEE Technical Committee on Model-Based Optimization is available here:

Example tasks

Quadruped task:

Rubik's cube 10-move unscramble:

Humanoid motion-capture tracking:

Graphical User Interface

For a detailed dive of the graphical user interface, see the MJPC GUI documentation.

Installation

You will need CMake and a working C++20 compiler to build MJPC. We recommend using VSCode and 2 of its extensions (CMake Tools and C/C++) to simplify the build process.

1. Clone the repository: git clone https://github.com/google-deepmind/mujoco_mpc.git
2. Configure the project with CMake (a pop-up should appear in VSCode)
3. Build and run the mjpc target in "release" mode (VSCode defaults to "debug"). This will open and run the graphical user interface.

macOS

Additionally, install Xcode.

Ubuntu

Additionally, install:

sudo apt-get install libgl1-mesa-dev libxinerama-dev libxcursor-dev libxrandr-dev libxi-dev ninja-build

Build Issues

If you encounter build issues, please see the Github Actions configuration. This provides the exact setup we use for building MJPC for testing.

We recommend building with clang and not gcc.

Python API

We provide a simple Python API for MJPC. This API is still experimental and expects some more experience from its users. For example, the correct usage requires that the model (defined in Python) and the MJPC task (i.e., the residual and transition functions defined in C++) are compatible with each other. Currently, the Python API does not provide any particular error handling for verifying this compatibility and may be difficult to debug without more in-depth knowledge about mujoco and MJPC.

Installing via Pip

First, build MJPC (see above).

Next, change to the python directory:

cd python

Install the Python module:

python setup.py install

Test that installation was successful:

python "mujoco_mpc/agent_test.py"

Additionally, the Python version of MuJoCo should match the MJPC version (this information can be found in the terminal while the application is running).

Example Usage

See cartpole.py for example usage for planning.

Predictive Control

See the Predictive Control documentation for more information.

Contributing

See the Contributing documentation for more information.

Known Issues

MJPC is not production-quality software, it is a research prototype. There are likely to be missing features and outright bugs. If you find any, please report them in the issue tracker. Below we list some known issues, including items that we are actively working on.

• We have not tested MJPC on Windows, but there should be no issues in principle.
• Task specification, in particular the setting of norms and their parameters in XML, is a bit clunky. We are still iterating on the design.
• The Gradient Descent search step is proportional to the scale of the cost function and requires per-task tuning in order to work well. This is not a bug but a property of vanilla gradient descent. It might be possible to ameliorate this with some sort of gradient normalisation, but we have not investigated this thoroughly.

Citation

If you use MJPC in your work, please cite our accompanying preprint:

@article{howell2022,
  title={{Predictive Sampling: Real-time Behaviour Synthesis with MuJoCo}},
  author={Howell, Taylor and Gileadi, Nimrod and Tunyasuvunakool, Saran and Zakka, Kevin and Erez, Tom and Tassa, Yuval},
  archivePrefix={arXiv},
  eprint={2212.00541},
  primaryClass={cs.RO},
  url={https://arxiv.org/abs/2212.00541},
  doi={10.48550/arXiv.2212.00541},
  year={2022},
  month={dec}
}

Acknowledgments

The main effort required to make this repository publicly available was undertaken by Taylor Howell and the Google DeepMind Robotics Simulation team.

License and Disclaimer

All other content is Copyright 2022 DeepMind Technologies Limited and licensed under the Apache License, Version 2.0. A copy of this license is provided in the top-level LICENSE file in this repository. You can also obtain it from https://www.apache.org/licenses/LICENSE-2.0.

This is not an officially supported Google product.