Project import.

Co-authored-by: Kevin Zakka <[email protected]>
Co-authored-by: Baruch Tabanpour <[email protected]>
Co-authored-by: Mustafa Haiderbhai <[email protected]>
Co-authored-by: Samuel Holt <[email protected]>
Co-authored-by: Jing Yuan Luo <[email protected]>
Co-authored-by: Arthur Allshire <[email protected]>
Co-authored-by: Qiayuan Liao <[email protected]>
Co-authored-by: Carlo Sferrazza <[email protected]>
PiperOrigin-RevId: 715549440
Change-Id: I6296fdb7e6bf9c3b5420e27ee0fd3555268d815a

Author: 8 people

.gitignore

@@ -1,39 +1,28 @@
-# Don't commit binaries
-*.a
-*.asm
-*.dll
-*.dylib
-*.exe
-*.lib
-*.out
-*.o
-*.so
-*.so.*
-
-# Exclude editor config
-.vscode/
-.vs/
-
-# Exclude temporary folders
-*.egg-info/
-build/
-build_cmake/
-python/dist/
-doc/_build
-
-# Exclude macOS folder attributes
 .DS_Store
-
-# Exclude macOS Info.framework.plist
-Info.framework.plist
-
-# Python byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# MuJoCo's default log file
+__pycache__
+*.egg-info
+checkpoints/
+dog_assets/
+videos/
+.vscode
+*.msh
+*.pt
+*.pkl
+*.mp4
+*.gif
+*.zip
+learning/*.png
+# Other.
+dog.py
+curriculum.ipynb
+**runs**/
+learning/wandb
 MUJOCO_LOG.TXT
-
-# Clang cache
-.cache/
+learning/*.png
+*.tar.gz
+**/logs/**
+**/wandb/**
+**/runs/**
+*.onnx
+!mujoco_playground/experimental/sim2sim/onnx/*.onnx
+**/.ipynb_checkpoints/

.pre-commit-config.yaml

@@ -0,0 +1,50 @@
+default_stages: [pre-commit]
+exclude: '.*__init__\.py$'
+
+# Install
+# 1. pip install -e .
+# 2. pre-commit install
+# 3. pre-commit run --all-files  # make sure all files are clean
+repos:
+  - repo: https://github.com/google/pyink
+    rev: 24.10.0
+    hooks:
+      - id: pyink
+        name: Pyink (Formatting)
+        # pyink will automatically read configuration from pyproject.toml
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        name: Isort (Import Sorting)
+        # isort will automatically read configuration from pyproject.toml
+
+  # - repo: local
+  #   hooks:
+  #     - id: pylint
+  #       name: Pylint (Google Style)
+  #       entry: pylint
+  #       args: ['--rcfile=pylintrc']
+  #       language: system
+  #       types: [python]
+
+  # - repo: local # re-using locally installed libraries
+  #   hooks:
+  #     - id: pytype
+  #       name: Pytype (Type Checking)
+  #       entry: pytype
+  #       language: system
+  #       types: [python]
+  #       always_run: true
+
+  # - repo: local
+  #   hooks:
+  #     - id: pytest
+  #       name: Run Pytest
+  #       entry: pytest
+  #       language: system
+  #       pass_filenames: false
+  #       always_run: true
+  #       args: ["-n", "auto"]  # Execute tests in parallel
+  #       verbose: true

CONTRIBUTING

@@ -23,3 +23,28 @@ information on using pull requests.
 
 This project follows [Google's Open Source Community
 Guidelines](https://opensource.google/conduct/).
+
+
+## Linting and Code Health
+
+Before submitting a PR, please run:
+
+```shell
+pip install -e ".[dev]"
+pre-commit install
+pre-commit run --all-files
+```
+
+or you can run manually
+
+```shell
+pyink .
+
+isort .
+
+pylint . --rcfile=pylintrc
+
+pytype .
+```
+
+And resolve any issues that pop up.

README.md

@@ -1,13 +1,84 @@
 # MuJoCo Playground
 
-MuJoCo Playground contains a suite of classic control and robotic environments built on top of the MuJoCo physics engine. Environments contain recipes for training classic control, locomotion, and manipulation behaviors via RL.
+<h1>
+  <a href="#"><img alt="MuJoCo Playground" src="assets/banner.png" width="100%"></a>
+</h1>
+
+A comprehensive suite of environments for robot learning research, accelerated by [MuJoCo MJX](https://github.com/google-deepmind/mujoco/tree/main/mjx).
+
+Features include:
+
+- Classic control environments from `dm_control` reimplemented in MJX
+- Quadruped and bipedal locomotion environments
+- Non-prehensile and dexterous manipulation environments
+- Vision-based support via Madrona
 
 ## Installation
 
 > [!IMPORTANT]
 > Requires Python 3.9 or later.
 
 1. `pip install -U "jax[cuda12]"`
-    * `python -c "import jax; print(jax.default_backend())"` should print `gpu`.
-2. Clone this repository.
-3. `pip install -e ".[all]"`
+    * Verify GPU backend: `python -c "import jax; print(jax.default_backend())"` should print `gpu`
+2. Clone this repository
+3. Install submodules: `git submodule update --init --recursive`
+4. `pip install -e ".[all]"`
+
+## Common Gotchas
+
+- Version mismatch between mjx and mujoco can cause issues. If encountered:
+    ```bash
+    pip uninstall mujoco mujoco-mjx
+    pip install --upgrade mujoco mujoco-mjx
+    ```
+
+## Playground environments
+
+### Locomotion Suite
+
+| Environment | Visualization
+|------------|---------------|
+| `Env1`     | [hopper.gif]  |
+| `Env2`     | [walker.gif]  |
+| `Env3`     | [humanoid.gif]|
+
+### Manipulation Suite
+
+| Environment | Description | Simulation | Real Robot |
+|------------|-------------|------------|------------|
+| `ReachEnv` | Reaching task with robot arm | [reach.gif] | [real_reach.gif] |
+| `PushEnv` | Object pushing with robot arm | [push.gif] | [real_push.gif] |
+| `PickPlaceEnv` | Pick and place objects | [pick.gif] | N/A |
+
+### DM Control Suite
+
+| Environment | Description | Simulation |
+|------------|-------------|------------|
+| `Cartpole` | Classic cartpole balancing | [cartpole.gif] |
+| `Pendulum` | Inverted pendulum control | [pendulum.gif] |
+| `Cheetah` | 2D cheetah running | [cheetah.gif] |
+| `Finger` | Finger spinning task | [finger.gif] |
+
+## Frequently Asked Questions
+
+* Q1
+* Q2
+* Q3
+
+## How can I contribute?
+
+Install the library and use it! Report bugs in the issue tracker. If you are a developer with some robotics experience looking to hack on open source, check out the [contribution guidelines](CONTRIBUTING).
+
+## Citation
+
+If you use Playground in your scientific works, please cite it as follows:
+
+```bibtex
+@misc{mujoco_playground2025,
+  author = {[Your Name]},
+  title = {MuJoCo Playground},
+  year = {2025},
+  publisher = {GitHub},
+  url = {https://github.com/google-deepmind/mujoco-playground}
+}
+```

assets/banner.png

@@ -0,0 +1,28 @@
+# Learning RL Agents
+
+In this directory, we demonstrate learning RL agents from MuJoCo Playground environments using [Brax](https://github.com/google/brax) and [RSL-RL](https://github.com/leggedrobotics/rsl_rl). We provide two entrypoints from the command line: `python train_jax_ppo.py` and `python train_rsl_rl.py`.
+
+For more detailed tutorials on using MuJoCo Playground for RL, see:
+
+1. Intro. to the Playground with DM Control Suite [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-deepmind/mujoco_playground/blob/main/learning/notebooks/dm_control_suite.ipynb)
+2. Locomotion Environments [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-deepmind/mujoco_playground/blob/main/learning/notebooks/locomotion.ipynb)
+3. Manipulation Environments [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-deepmind/mujoco_playground/blob/main/learning/notebooks/manipulation.ipynb)
+4. Training CartPole from Vision [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-deepmind/mujoco_playground/blob/main/learning/training_vision_1.ipynb)
+5. Robotic Manipulation from Vision [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-deepmind/mujoco_playground/blob/main/learning/training_vision_2.ipynb)
+
+## Training with RSL-RL
+
+To train with RSL-RL, you can use the `train_rsl_rl.py` script. This script uses the RSL-RL algorithm to train an agent on a given environment.
+
+```bash
+python train_rsl_rl.py --env_name=LeapCubeReorient
+```
+
+to render the behaviour from the resulting policy:
+```bash
+python learning/train_rsl_rl.py --env_name LeapCubeReorient --play_only --load_run_name <run_name>
+```
+
+where `run_name` is the name of the run you want to load (will be printed in the console when the training run is started).
+
+Logs and checkpoints are saved in `logs` directory.