https://github.com/mgross21/mujoco-toolbox
A Modern Simulation Wrapper for Google DeepMind’s MuJoCo
https://github.com/mgross21/mujoco-toolbox
mujoco physics-simulation python wrapper-library
Last synced: 3 months ago
JSON representation
A Modern Simulation Wrapper for Google DeepMind’s MuJoCo
- Host: GitHub
- URL: https://github.com/mgross21/mujoco-toolbox
- Owner: MGross21
- License: mit
- Created: 2024-12-05T01:37:17.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-06-02T08:45:24.000Z (4 months ago)
- Last Synced: 2025-06-02T11:25:02.997Z (4 months ago)
- Topics: mujoco, physics-simulation, python, wrapper-library
- Language: Python
- Homepage: https://mgross21.github.io/mujoco-toolbox/
- Size: 13.5 MB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
Awesome Lists containing this project
README
[](https://github.com/MGross21/mujoco-toolbox/actions/workflows/publish.yml)
[](https://github.com/MGross21/mujoco-toolbox/actions/workflows/docs.yml)
A Modern Simulation Wrapper for Google DeepMind’s MuJoCo
> **⚠️ WARNING**
> This package is currently in its zero-release stage. Class methods and APIs may change without prior notice. Please review the documentation and changelog after each update to stay informed about any modifications.
## Installation
*Add `-U` flag to upgrade pre-existing library*
### PyPI Package
[](https://pypi.org/project/mujoco-toolbox/)
```bash
pip install mujoco-toolbox
```
### GitHub Package
[](https://github.com/MGross21/mujoco-toolbox/releases)
```bash
pip install git+https://github.com/MGross21/mujoco-toolbox.git@main
```
### Adding to Project Dependencies
Click to Expand
Place the following in your `requirements.txt` or `pyproject.toml` file.
### PyPI
Expect less frequent, stable releases.
```
mujoco-toolbox
```
### Github
Expect frequent rolling releases.
```
git+https://github.com/MGross21/mujoco-toolbox.git@main#egg=mujoco-toolbox
```
## Extra Packages
FFMPEG
*Required for [mediapy](https://google.github.io/mediapy/mediapy.html) dependency*
**Windows**
```bash
winget install ffmpeg
ffmpeg -version
```
**Linux**
*Debian/Ubuntu*
```bash
sudo apt update && sudo apt install ffmpeg
ffmpeg -version
```
*Arch Linux*
```bash
sudo pacman -Syu ffmpeg
ffmpeg -version
```
**MacOS**
*Using Homebrew*
```bash
brew install ffmpeg
ffmpeg -version
```
*Using MacPorts*
```bash
sudo port install ffmpeg
ffmpeg -version
```
## Example Script
*Bare minimum to run MuJoCo simulation and display result*
```python
import mujoco_toolbox as mjtb
mjtb.Simulation("path/to/your/xml").run(render=True).save()
```
## Controllers
### Pre-Made Controllers
The following controllers are available out-of-the-box:
- `sin`
- `cos`
- `step`
- `random`
- `real_time` (recommended controller for digital twins)
You can import them as follows:
```python
import mujoco_toolbox.controllers as ctrl
```
### Custom
```python
def foo(model: MjModel, data: MjData,**kwargs):
# Perform logic based on model/data objects
# ie. PID Controller
```
## Instantiating a Digital Twin
```python
import mujoco_toolbox as mjtb
from mujoco_toolbox.controllers import real_time
with mjtb.Simulation("path/to/xml", controller=real_time) as digitaltwin:
digitaltwin.launch(show_menu=False) # Open the simulation window
while True:
digitaltwin.controller(digitaltwin.model, digitaltwin.data, {"mjdata_kwargs": value})
```
See `MjData` objects [here](https://mujoco.readthedocs.io/en/stable/APIreference/APItypes.html#mjdata)
## File Support
### XML / MJCF (Native)
```python
import mujoco_toolbox as mjtb
mjtb.Simulation("path/to/xml").show()
```
### URDF
```python
import mujoco_toolbox as mjtb
mjtb.Simulation("path/to/urdf", meshdir="path/to/mesh/files").show() # supports *.stl or *.obj
```
## Merging Capabilities
Supports full `...` and `...` structure as well as complete sub-tree structures.
```python
import mujoco_toolbox as mjtb
# Merges: XML & URDF Files, XML & URDF Strings, Sub Tree Structures
mjtb.Simulation("path/to/xml_1", string_xml_var, ..., "path/to/xml_n").show()
```
> **⚠️ WARNING**
> Duplicate sub-tree items with the same name will cause MuJoCo to throw a `FatalError`.
