google-deepmind/mujoco_mpc

google-deepmind/mujoco_mpc

Description: Real-time behaviour synthesis with MuJoCo, using Predictive Control

Language: C++

License: Apache-2.0

Stars: 1662

Forks: 267

Open issues: 53

Created: 2022-12-01T11:39:35Z

Pushed: 2026-06-10T19:27:45Z

Default branch: main

Fork: no

Archived: no

README:

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](#overview)
• [Graphical User Interface](#graphical-user-interface)
• [Installation](#installation)
• [macOS](#macos)
• [Ubuntu](#ubuntu)
• [Build Issues](#build-issues)
• [Predictive Control](#predictive-control)
• [Contributing](#contributing)
• [Known Issues](#known-issues)
• [Citation](#citation)
• [Acknowledgments](#acknowledgments)
• [License and Disclaimer](#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:


Bimanual manipulation:


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](docs/GUI.md) documentation.

Installation

MJPC is tested with Ubuntu 20.04 and macOS-12. In principle, other versions and Windows operating system should work with MJPC, but these are not tested.

Prerequisites

Operating system specific dependencies:

macOS

Install Xcode.

Install ninja and zlib:

brew install ninja zlib

Ubuntu 20.04

sudo apt-get update && sudo apt-get install cmake libgl1-mesa-dev libxinerama-dev libxcursor-dev libxrandr-dev libxi-dev ninja-build zlib1g-dev clang-12

Clone MuJoCo MPC

git clone https://github.com/google-deepmind/mujoco_mpc

Build and Run MJPC GUI application

1. Change directory:

cd mujoco_mpc

2. Create and change to build directory:

mkdir build
cd build

3. Configure:

macOS-12

cmake .. -DCMAKE_BUILD_TYPE:STRING=Release -G Ninja -DMJPC_BUILD_GRPC_SERVICE:BOOL=ON

Ubuntu 20.04

cmake .. -DCMAKE_BUILD_TYPE:STRING=Release -G Ninja -DCMAKE_C_COMPILER:STRING=clang-12 -DCMAKE_CXX_COMPILER:STRING=clang++-12 -DMJPC_BUILD_GRPC_SERVICE:BOOL=ON

Note: gRPC is a large dependency and can take 10-20 minutes to initially download.

4. Build

cmake --build . --config=Release

6. Run GUI application

cd bin
./mjpc

Build and Run MJPC GUI application using VSCode

We recommend using VSCode and 2 of its extensions (CMake Tools and C/C++) to simplify the build process.

1. Open the cloned directory mujoco_mpc. 2. Configure the project with CMake (a pop-up should appear in VSCode) 3. Set compiler to clang-12. 4. Build and run the mjpc target in "release" mode (VSCode defaults to "debug"). This will open and run the graphical user interface.

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 with Ubuntu 20.04 and macOS-12.

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.

Installation

Prerequisites

1. Build MJPC (see instructions above).

2. Python 3.10

3. (Optionally) Create a conda environment with Python 3.10:

conda create -n mjpc python=3.10
conda activate mjpc

4. Install MuJoCo

pip install mujoco

Install API

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"

Example scripts are found in python/mujoco_mpc/demos. For example from python/:

python mujoco_mpc/demos/agent/cartpole_gui.py

will run the MJPC GUI application using MuJoCo's passive viewer via Python.

Python API Installation Issues

If your installation fails or is terminated prematurely, we recommend deleting the MJPC build directory and starting from scratch as the build will likely be corrupted. Additionally, delete the files generated during the installation process from the python/ directory.

Predictive Control

See the [Predictive Control](docs/OVERVIEW.md) documentation for…