diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3fdb009..8162b4a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,6 +12,26 @@ You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again. +## Adding New Tasks + +We welcome contributions of new tasks, particularly those that demonstrate: + +- Impressive capabilities in simulation +- Tasks that have been successfully transferred to real robots + +When submitting a new task, please ensure: + +1. The task is well-documented with clear objectives and reward structure +2. Add the relevant RL hyperparameters to the config file so that it can be + independently reproduced +3. Ensure that it works across at least 3 seeds +4. Show a video of the behavior +5. Make sure your new task passes all the tests + +For an example of a well-structured task contribution, see @Andrew-Luo1's +excellent [ALOHA Handover Task +PR](https://github.com/google-deepmind/mujoco_playground/pull/29). + ## Code reviews All submissions, including submissions by project members, require review. We @@ -24,7 +44,6 @@ 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: @@ -39,12 +58,18 @@ or you can run manually ```shell pyink . - isort . - pylint . --rcfile=pylintrc - pytype . ``` -And resolve any issues that pop up. +and resolve any issues that pop up. + +## Testing + +To run the tests, use the following command: + +```shell +pytest +``` + diff --git a/README.md b/README.md index be819a4..64849b9 100644 --- a/README.md +++ b/README.md @@ -40,38 +40,29 @@ For vision-based environments, please refer to the installation instructions in ## Getting started -To try out MuJoCo Playground locally on a simple locomotion environment, you can run the following: - -```py -import jax -import jax.numpy as jp -from mujoco_playground import registry - -env = registry.load('Go1JoystickFlatTerrain') -state = jax.jit(env.reset)(jax.random.PRNGKey(0)) -print(state.obs) -state = jax.jit(env.step)(state, jp.zeros(env.action_size)) -print(state.obs) -``` - -For detailed tutorials on using MuJoCo Playground, see: - -1. [Intro. to the Playground with DM Control Suite](https://colab.research.google.com/github/google-deepmind/mujoco_playground/blob/main/learning/notebooks/dm_control_suite.ipynb) [![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](https://colab.research.google.com/github/google-deepmind/mujoco_playground/blob/main/learning/notebooks/locomotion.ipynb) [![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](https://colab.research.google.com/github/google-deepmind/mujoco_playground/blob/main/learning/notebooks/manipulation.ipynb) [![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) - -For tutorials on MuJoCo Playground with Madrona-MJX batch rendering, we offer two types of colabs. The first allows you to install Madrona-MJX directly in a GPU colab instance and run vision-based cartpole! - -1. [Training CartPole from Vision](https://colab.research.google.com/github/google-deepmind/mujoco_playground/blob/main/learning/notebooks/training_vision_1_t4.ipynb) on a Colab T4 Instance [![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/training_vision_1_t4.ipynb) - -Two additional colabs require local runtimes with Madrona-MJX installed locally (see [Madrona-MJX](https://github.com/shacklettbp/madrona_mjx?tab=readme-ov-file#installation) for installation instructions): - -1. [Training CartPole from Vision (Local Runtime)](https://colab.research.google.com/github/google-deepmind/mujoco_playground/blob/main/learning/notebooks/training_vision_1.ipynb) [![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/training_vision_1.ipynb) -2. [Robotic Manipulation from Vision (Local Runtime)](https://colab.research.google.com/github/google-deepmind/mujoco_playground/blob/main/learning/notebooks/training_vision_2.ipynb) [![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/training_vision_2.ipynb) +### Basic Tutorials +| Colab | Description | +|-------|-------------| +| [![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) | Introduction 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/locomotion.ipynb) | 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/manipulation.ipynb) | Manipulation Environments | + +### Vision-Based Tutorials (GPU Colab) +| Colab | Description | +|-------|-------------| +| [![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/training_vision_1_t4.ipynb) | Training CartPole from Vision (T4 Instance) | + +### Local Runtime Tutorials +*Requires local Madrona-MJX installation* + +| Colab | Description | +|-------|-------------| +| [![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/training_vision_1.ipynb) | 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/notebooks/training_vision_2.ipynb) | Robotic Manipulation from Vision | ## How can I contribute? -Get started by installing the library and exploring its features! Found a bug? Report it in the issue tracker. Interested in contributing? If you’re a developer with robotics experience, we’d love your help—check out the [contribution guidelines](CONTRIBUTING.md) for more details. +Get started by installing the library and exploring its features! Found a bug? Report it in the issue tracker. Interested in contributing? If you are a developer with robotics experience, we would love your help—check out the [contribution guidelines](CONTRIBUTING.md) for more details. ## Citation