{"id":28753296,"url":"https://github.com/google-deepmind/mujoco_mpc","last_synced_at":"2025-06-17T00:39:29.448Z","repository":{"id":64083365,"uuid":"572952605","full_name":"google-deepmind/mujoco_mpc","owner":"google-deepmind","description":"Real-time behaviour synthesis with MuJoCo, using Predictive Control","archived":false,"fork":false,"pushed_at":"2025-05-07T12:07:02.000Z","size":10419,"stargazers_count":1252,"open_issues_count":43,"forks_count":198,"subscribers_count":27,"default_branch":"main","last_synced_at":"2025-05-07T13:24:21.178Z","etag":null,"topics":["model-predictive-control","motor-control","mpc","mpc-control","mujoco","predictive-control"],"latest_commit_sha":null,"homepage":"https://github.com/deepmind/mujoco_mpc","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google-deepmind.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.bib","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-12-01T11:39:35.000Z","updated_at":"2025-05-07T08:33:00.000Z","dependencies_parsed_at":"2023-10-02T07:58:03.610Z","dependency_job_id":"e8681a88-5f9c-4207-805f-446c0c184d26","html_url":"https://github.com/google-deepmind/mujoco_mpc","commit_stats":null,"previous_names":["google-deepmind/mujoco_mpc","deepmind/mujoco_mpc"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/google-deepmind/mujoco_mpc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fmujoco_mpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fmujoco_mpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fmujoco_mpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fmujoco_mpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google-deepmind","download_url":"https://codeload.github.com/google-deepmind/mujoco_mpc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fmujoco_mpc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260268635,"owners_count":22983601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["model-predictive-control","motor-control","mpc","mpc-control","mujoco","predictive-control"],"created_at":"2025-06-17T00:39:28.645Z","updated_at":"2025-06-17T00:39:29.416Z","avatar_url":"https://github.com/google-deepmind.png","language":"C++","funding_links":[],"categories":["🦿 Humanoid \u0026 Legged Robots"],"sub_categories":[],"readme":"\u003ch1\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"MuJoCo MPC\" src=\"docs/assets/banner.png\" width=\"100%\"\u003e\u003c/a\u003e\n\u003c/h1\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/google-deepmind/mujoco_mpc/actions/workflows/build.yml?query=branch%3Amain\" alt=\"GitHub Actions\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/google-deepmind/mujoco_mpc/build.yml?branch=main\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/google-deepmind/mujoco_mpc/blob/main/LICENSE\" alt=\"License\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/google-deepmind/mujoco_mpc\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n**MuJoCo MPC (MJPC)** is an interactive application and software framework for\nreal-time predictive control with [MuJoCo](https://mujoco.org/), developed by\nGoogle DeepMind.\n\nMJPC allows the user to easily author and solve complex robotics tasks, and\ncurrently supports multiple shooting-based planners. Derivative-based methods include iLQG and\nGradient Descent, while derivative-free methods include a simple yet very competitive planner\ncalled Predictive Sampling.\n\n- [Overview](#overview)\n- [Graphical User Interface](#graphical-user-interface)\n- [Installation](#installation)\n  - [macOS](#macos)\n  - [Ubuntu](#ubuntu)\n  - [Build Issues](#build-issues)\n- [Predictive Control](#predictive-control)\n- [Contributing](#contributing)\n- [Known Issues](#known-issues)\n- [Citation](#citation)\n- [Acknowledgments](#acknowledgments)\n- [License and Disclaimer](#license-and-disclaimer)\n\n## Overview\n\nTo read the paper describing this software package, please see our\n[preprint](https://arxiv.org/abs/2212.00541).\n\nFor a quick video overview of MJPC, click below.\n\n[![Video](http://img.youtube.com/vi/Bdx7DuAMB6o/hqdefault.jpg)](https://dpmd.ai/mjpc)\n\nFor a longer talk at the MIT Robotics Seminar in December 2022 describing our results, click\nbelow.\n\n[![2022Talk](http://img.youtube.com/vi/2xVN-qY78P4/hqdefault.jpg)](https://www.youtube.com/watch?v=2xVN-qY78P4)\n\nA more recent, December 2023 talk at the IEEE Technical Committee on Model-Based Optimization\nis available here:\n\n[![2023Talk](https://img.youtube.com/vi/J-JO-lgaKtw/hqdefault.jpg)](https://www.youtube.com/watch?v=J-JO-lgaKtw\u0026t=0s)\n\n### Example tasks\n\nQuadruped task:\n\n[![Quadruped](http://img.youtube.com/vi/esLuwaWz4oE/hqdefault.jpg)](https://www.youtube.com/watch?v=esLuwaWz4oE)\n\n\nBimanual manipulation:\n\n[![Bimanual](http://img.youtube.com/vi/aCNCKVThKIE/hqdefault.jpg)](https://www.youtube.com/watch?v=aCNCKVThKIE)\n\n\nRubik's cube 10-move unscramble:\n\n[![Unscramble](http://img.youtube.com/vi/ZRRvVWV-Muk/hqdefault.jpg)](https://www.youtube.com/watch?v=ZRRvVWV-Muk)\n\nHumanoid motion-capture tracking:\n\n[![Tracking](http://img.youtube.com/vi/tEBVK-MO1Sw/hqdefault.jpg)](https://www.youtube.com/watch?v=tEBVK-MO1Sw)\n\n## Graphical User Interface\n\nFor a detailed dive of the graphical user interface, see the\n[MJPC GUI](docs/GUI.md) documentation.\n\n## Installation\nMJPC is tested with [Ubuntu 20.04](https://releases.ubuntu.com/focal/) and [macOS-12](https://www.apple.com/by/macos/monterey/). In principle, other versions and Windows operating system should work with MJPC, but these are not tested.\n\n### Prerequisites\nOperating system specific dependencies:\n\n#### macOS\nInstall [Xcode](https://developer.apple.com/xcode/).\n\nInstall `ninja` and `zlib`:\n```sh\nbrew install ninja zlib\n```\n\n#### Ubuntu 20.04\n```sh\nsudo apt-get update \u0026\u0026 sudo apt-get install cmake libgl1-mesa-dev libxinerama-dev libxcursor-dev libxrandr-dev libxi-dev ninja-build zlib1g-dev clang-12\n```\n\n### Clone MuJoCo MPC\n```sh\ngit clone https://github.com/google-deepmind/mujoco_mpc\n```\n\n### Build and Run MJPC GUI application\n1. Change directory:\n```sh\ncd mujoco_mpc\n```\n\n2. Create and change to build directory:\n```sh\nmkdir build\ncd build\n```\n\n3. Configure:\n\n#### macOS-12\n```sh\ncmake .. -DCMAKE_BUILD_TYPE:STRING=Release -G Ninja -DMJPC_BUILD_GRPC_SERVICE:BOOL=ON\n```\n\n#### Ubuntu 20.04\n```sh\ncmake .. -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\n```\n**Note: gRPC is a large dependency and can take 10-20 minutes to initially download.**\n\n4. Build\n```sh\ncmake --build . --config=Release\n```\n\n6. Run GUI application\n```sh\ncd bin\n./mjpc\n```\n\n### Build and Run MJPC GUI application using VSCode\nWe recommend using [VSCode](https://code.visualstudio.com/) and 2 of its\nextensions ([CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)\nand [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools))\nto simplify the build process.\n\n1. Open the cloned directory `mujoco_mpc`.\n2. Configure the project with CMake (a pop-up should appear in VSCode)\n3. Set compiler to `clang-12`.\n4. Build and run the `mjpc` target in \"release\" mode (VSCode defaults to\n   \"debug\"). This will open and run the graphical user interface.\n\n### Build Issues\nIf you encounter build issues, please see the\n[Github Actions configuration](https://github.com/google-deepmind/mujoco_mpc/blob/main/.github/workflows/build.yml).\nThis provides the exact setup we use for building MJPC for testing with Ubuntu 20.04 and macOS-12.\n\n# Python API\nWe 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.\n\n## Installation\n\n### Prerequisites\n1. Build MJPC (see instructions above).\n\n2. Python 3.10\n\n3. (Optionally) Create a conda environment with **Python 3.10**:\n```sh\nconda create -n mjpc python=3.10\nconda activate mjpc\n```\n\n4. Install MuJoCo\n```sh\npip install mujoco\n```\n\n### Install API\nNext, change to the python directory:\n```sh\ncd python\n```\n\nInstall the Python module:\n```sh\npython setup.py install\n```\n\nTest that installation was successful:\n```sh\npython \"mujoco_mpc/agent_test.py\"\n```\n\nExample scripts are found in `python/mujoco_mpc/demos`. For example from `python/`:\n```sh\npython mujoco_mpc/demos/agent/cartpole_gui.py\n```\nwill run the MJPC GUI application using MuJoCo's passive viewer via Python.\n\n### Python API Installation Issues\nIf 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.\n\n## Predictive Control\n\nSee the [Predictive Control](docs/OVERVIEW.md) documentation for more\ninformation.\n\n## Contributing\n\nSee the [Contributing](docs/CONTRIBUTING.md) documentation for more information.\n\n## Known Issues\n\nMJPC is not production-quality software, it is a **research prototype**. There\nare likely to be missing features and outright bugs. If you find any, please\nreport them in the [issue tracker](https://github.com/google-deepmind/mujoco_mpc/issues).\nBelow we list some known issues, including items that we are actively working\non.\n\n- We have not tested MJPC on Windows, but there should be no issues in\n  principle.\n- Task specification, in particular the setting of norms and their parameters in\n  XML, is a bit clunky. We are still iterating on the design.\n- The Gradient Descent search step is proportional to the scale of the cost\n  function and requires per-task tuning in order to work well. This is not a bug\n  but a property of vanilla gradient descent. It might be possible to ameliorate\n  this with some sort of gradient normalisation, but we have not investigated\n  this thoroughly.\n\n## Citation\n\nIf you use MJPC in your work, please cite our accompanying [preprint](https://arxiv.org/abs/2212.00541):\n\n```bibtex\n@article{howell2022,\n  title={{Predictive Sampling: Real-time Behaviour Synthesis with MuJoCo}},\n  author={Howell, Taylor and Gileadi, Nimrod and Tunyasuvunakool, Saran and Zakka, Kevin and Erez, Tom and Tassa, Yuval},\n  archivePrefix={arXiv},\n  eprint={2212.00541},\n  primaryClass={cs.RO},\n  url={https://arxiv.org/abs/2212.00541},\n  doi={10.48550/arXiv.2212.00541},\n  year={2022},\n  month={dec}\n}\n```\n\n## Acknowledgments\n\nThe main effort required to make this repository publicly available was\nundertaken by [Taylor Howell](https://thowell.github.io/) and the Google\nDeepMind Robotics Simulation team.\n\n## License and Disclaimer\n\nAll other content is Copyright 2022 DeepMind Technologies Limited and licensed\nunder the Apache License, Version 2.0. A copy of this license is provided in the\ntop-level LICENSE file in this repository. You can also obtain it from\nhttps://www.apache.org/licenses/LICENSE-2.0.\n\nThis is not an officially supported Google product.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-deepmind%2Fmujoco_mpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle-deepmind%2Fmujoco_mpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-deepmind%2Fmujoco_mpc/lists"}