Skip to content

Commit

Permalink
Improve README and CONTRIBUTING.
Browse files Browse the repository at this point in the history 
PiperOrigin-RevId: 718055094
Change-Id: I94ce4c8495794d6f7313e9f2f0dc72c9cc19fbc2
  • Loading branch information
@kevinzakka @copybara-github
kevinzakka authored and copybara-github committed Jan 21, 2025
1 parent 7dc538b commit 2034ac0
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 34 deletions.
35 changes: 30 additions & 5 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -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
```

49 changes: 20 additions & 29 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down

0 comments on commit 2034ac0

Please sign in to comment.