Name | loco-mujoco JSON |
Version |
0.4.1
JSON |
| download |
home_page | https://github.com/robfiras/loco-mujoco |
Summary | Imitation learning benchmark focusing on complex locomotion tasks using MuJoCo. |
upload_time | 2024-09-13 15:29:28 |
maintainer | None |
docs_url | None |
author | Firas Al-Hafez |
requires_python | >=3.8 |
license | MIT License Copyright (c) 2024 Al-Hafez Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
keywords |
imitation learning
reinforcement learning
locomotion
|
VCS |
|
bugtrack_url |
|
requirements |
mushroom-rl
numpy
scipy
mujoco
gymnasium
dm_control
pyyaml
wget
gitpython
|
Travis-CI |
No Travis.
|
coveralls test coverage |
No coveralls.
|
<p align="center">
<img width="70%" src="https://github.com/robfiras/loco-mujoco/assets/69359729/bd2a219e-ddfd-4355-8024-d9af921fb92a">
</p>
![continous integration](https://github.com/robfiras/loco-mujoco/actions/workflows/continuous_integration.yml/badge.svg?branch=dev)
[![Documentation Status](https://readthedocs.org/projects/loco-mujoco/badge/?version=latest)](https://loco-mujoco.readthedocs.io/en/latest/?badge=latest)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI](https://img.shields.io/pypi/v/loco-mujoco)](https://pypi.org/project/loco-mujoco/)
[![Join our Discord](https://img.shields.io/badge/Discord-Join%20Us-7289DA?style=flat&logo=discord&logoColor=white)](https://discord.gg/gEqR3xCVdn)
**LocoMuJoCo** is an **imitation learning benchmark** specifically targeted towards **locomotion**. It encompasses a diverse set of environments, including quadrupeds, bipeds, and musculoskeletal human models, each accompanied by comprehensive datasets, such as real noisy motion capture data, ground truth expert data, and ground truth sub-optimal data,
enabling evaluation across a spectrum of difficulty levels.
**LocoMuJoCo** also allows you to specify your own reward function to use this benchmark for **pure reinforcement learning**! Checkout the example below!
<p align="center">
<img src="https://github.com/robfiras/loco-mujoco/assets/69359729/c16dfa4a-4fdb-4701-9a42-54cbf7644301">
</p>
### Key Advantages
✅ Easy to use with [Gymnasium](https://github.com/Farama-Foundation/Gymnasium) or [Mushroom-RL](https://github.com/MushroomRL/mushroom-rl) interface \
✅ Many environments including humanoids and quadrupeds \
✅ Diverse set of datasets --> e.g., noisy motion capture or ground truth datasets with actions \
✅ Wide spectrum of difficulty levels \
✅ Built-in domain randomization \
✅ Many baseline algorithms for quick benchmarking \
✅ [Documentation](https://loco-mujoco.readthedocs.io/)
---
## Installation
You have the choice to install the latest release via PyPI by running
```bash
pip install loco-mujoco
```
or you do an editable installation by cloning this repository and then running:
```bash
cd loco-mujoco
pip install -e .
```
> [!NOTE]
> We fixed the version of MuJoCo to 2.3.7 during installation since we found that there are slight
> differences in the simulation, which made testing very difficult. However, in practice, you can
> use any newer version of MuJoCo! Just install it after installing LocoMuJoCo.
> [!NOTE]
> If you want to run the **MyoSkeleton** environment, you need to additionally run
> `loco-mujoco-myomodel-init` to accept the license and download the model. Finally, you need to
> upgrade Mujoco to 3.2.2 and dm_control to 1.0.22 *after* installing this package and downloading the datasets!
### Download the Datasets
After installing LocoMuJoCo, new commands for downloading the datasets will be setup for you.
You have the choice of downloading all datasets available or only the ones you need.
For example, to install all datasets run:
```bash
loco-mujoco-download
```
To install only the real (motion capture, no actions) datasets run:
```bash
loco-mujoco-download-real
```
To install only the perfect (ground-truth with actions) datasets run:
```bash
loco-mujoco-download-perfect
```
### Installing the Baselines
If you also want to run the baselines, you have to install our imitation learning library [imitation_lib](https://github.com/robfiras/ls-iq). You find example files for training the baselines for any LocoMuJoCo task [here](examples/imitation_learning).
### First Test
To verify that everything is installed correctly, run the examples such as:
```bash
python examples/simple_mushroom_env/example_unitree_a1.py
```
To replay a dataset run:
```bash
python examples/replay_datasets/replay_Unitree.py
```
---
## Environments & Tasks
You want a quick overview of all **environments**, **tasks** and **datasets** available? You can find it
[here](/loco_mujoco/environments) and more detailed in the [Documentation](https://loco-mujoco.readthedocs.io/).
<p align="center">
<img src="https://github.com/robfiras/loco-mujoco/assets/69359729/73ca0cdd-3958-4d59-a1f7-0eba00fe373a">
</p>
And stay tuned! There are many more to come ...
---
## Quick Examples
LocoMuJoCo is very easy to use. Just choose and create the environment, and generate the dataset belonging to this task and you are ready to go!
```python
import numpy as np
import loco_mujoco
import gymnasium as gym
env = gym.make("LocoMujoco", env_name="HumanoidTorque.run")
dataset = env.create_dataset()
```
You want to use LocoMuJoCo for pure reinforcement learning? No problem! Just define your custom reward function and pass it to the environment!
```python
import numpy as np
import loco_mujoco
import gymnasium as gym
import numpy as np
def my_reward_function(state, action, next_state):
return -np.mean(action)
env = gym.make("LocoMujoco", env_name="HumanoidTorque.run", reward_type="custom",
reward_params=dict(reward_callback=my_reward_function))
```
LocoMuJoCo *natively* supports [MushroomRL](https://github.com/MushroomRL/mushroom-rl):
```python
import numpy as np
from loco_mujoco import LocoEnv
env = LocoEnv.make("HumanoidTorque.run")
dataset = env.create_dataset()
```
You can find many more examples [here](examples).
Detailed Tutorials are given in the [Documentation](https://loco-mujoco.readthedocs.io/).
---
## Citation
```
@inproceedings{alhafez2023b,
title={LocoMuJoCo: A Comprehensive Imitation Learning Benchmark for Locomotion},
author={Firas Al-Hafez and Guoping Zhao and Jan Peters and Davide Tateo},
booktitle={6th Robot Learning Workshop, NeurIPS},
year={2023}
}
```
---
## Credits
Both Unitree models were taken from the [MuJoCo menagerie](https://github.com/google-deepmind/mujoco_menagerie)
Raw data
{
"_id": null,
"home_page": "https://github.com/robfiras/loco-mujoco",
"name": "loco-mujoco",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Firas Al-Hafez <fi.alhafez@gmail.com>",
"keywords": "Imitation Learning, Reinforcement Learning, Locomotion",
"author": "Firas Al-Hafez",
"author_email": "Firas Al-Hafez <fi.alhafez@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/36/6b/fe0ad7af1ebd12b246f4710aa21a5222bfaf4e0bcc31e1020908987867f0/loco-mujoco-0.4.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img width=\"70%\" src=\"https://github.com/robfiras/loco-mujoco/assets/69359729/bd2a219e-ddfd-4355-8024-d9af921fb92a\">\n</p>\n\n![continous integration](https://github.com/robfiras/loco-mujoco/actions/workflows/continuous_integration.yml/badge.svg?branch=dev)\n[![Documentation Status](https://readthedocs.org/projects/loco-mujoco/badge/?version=latest)](https://loco-mujoco.readthedocs.io/en/latest/?badge=latest)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPI](https://img.shields.io/pypi/v/loco-mujoco)](https://pypi.org/project/loco-mujoco/)\n[![Join our Discord](https://img.shields.io/badge/Discord-Join%20Us-7289DA?style=flat&logo=discord&logoColor=white)](https://discord.gg/gEqR3xCVdn)\n\n\n**LocoMuJoCo** is an **imitation learning benchmark** specifically targeted towards **locomotion**. It encompasses a diverse set of environments, including quadrupeds, bipeds, and musculoskeletal human models, each accompanied by comprehensive datasets, such as real noisy motion capture data, ground truth expert data, and ground truth sub-optimal data,\nenabling evaluation across a spectrum of difficulty levels. \n\n**LocoMuJoCo** also allows you to specify your own reward function to use this benchmark for **pure reinforcement learning**! Checkout the example below!\n\n<p align=\"center\">\n <img src=\"https://github.com/robfiras/loco-mujoco/assets/69359729/c16dfa4a-4fdb-4701-9a42-54cbf7644301\">\n</p>\n\n### Key Advantages \n\u2705 Easy to use with [Gymnasium](https://github.com/Farama-Foundation/Gymnasium) or [Mushroom-RL](https://github.com/MushroomRL/mushroom-rl) interface \\\n\u2705 Many environments including humanoids and quadrupeds \\\n\u2705 Diverse set of datasets --> e.g., noisy motion capture or ground truth datasets with actions \\\n\u2705 Wide spectrum of difficulty levels \\\n\u2705 Built-in domain randomization \\\n\u2705 Many baseline algorithms for quick benchmarking \\\n\u2705 [Documentation](https://loco-mujoco.readthedocs.io/)\n\n---\n\n## Installation\n\nYou have the choice to install the latest release via PyPI by running \n\n```bash\npip install loco-mujoco \n```\n\nor you do an editable installation by cloning this repository and then running:\n\n```bash\ncd loco-mujoco\npip install -e . \n```\n\n> [!NOTE]\n> We fixed the version of MuJoCo to 2.3.7 during installation since we found that there are slight \n> differences in the simulation, which made testing very difficult. However, in practice, you can \n> use any newer version of MuJoCo! Just install it after installing LocoMuJoCo.\n\n> [!NOTE]\n> If you want to run the **MyoSkeleton** environment, you need to additionally run\n> `loco-mujoco-myomodel-init` to accept the license and download the model. Finally, you need to \n> upgrade Mujoco to 3.2.2 and dm_control to 1.0.22 *after* installing this package and downloading the datasets! \n\n\n### Download the Datasets\nAfter installing LocoMuJoCo, new commands for downloading the datasets will be setup for you.\nYou have the choice of downloading all datasets available or only the ones you need.\n\nFor example, to install all datasets run: \n```bash\nloco-mujoco-download\n```\n\nTo install only the real (motion capture, no actions) datasets run: \n```bash\nloco-mujoco-download-real\n```\n\nTo install only the perfect (ground-truth with actions) datasets run: \n```bash\nloco-mujoco-download-perfect\n```\n\n### Installing the Baselines\nIf you also want to run the baselines, you have to install our imitation learning library [imitation_lib](https://github.com/robfiras/ls-iq). You find example files for training the baselines for any LocoMuJoCo task [here](examples/imitation_learning).\n\n### First Test\nTo verify that everything is installed correctly, run the examples such as:\n\n```bash\npython examples/simple_mushroom_env/example_unitree_a1.py\n```\n\nTo replay a dataset run:\n\n```bash\npython examples/replay_datasets/replay_Unitree.py\n```\n---\n## Environments & Tasks\nYou want a quick overview of all **environments**, **tasks** and **datasets** available? You can find it \n[here](/loco_mujoco/environments) and more detailed in the [Documentation](https://loco-mujoco.readthedocs.io/).\n\n<p align=\"center\">\n <img src=\"https://github.com/robfiras/loco-mujoco/assets/69359729/73ca0cdd-3958-4d59-a1f7-0eba00fe373a\">\n</p>\n\nAnd stay tuned! There are many more to come ...\n\n---\n## Quick Examples\nLocoMuJoCo is very easy to use. Just choose and create the environment, and generate the dataset belonging to this task and you are ready to go! \n```python\nimport numpy as np\nimport loco_mujoco\nimport gymnasium as gym\n\n\nenv = gym.make(\"LocoMujoco\", env_name=\"HumanoidTorque.run\")\ndataset = env.create_dataset()\n```\nYou want to use LocoMuJoCo for pure reinforcement learning? No problem! Just define your custom reward function and pass it to the environment!\n\n```python\nimport numpy as np\nimport loco_mujoco\nimport gymnasium as gym\nimport numpy as np\n\n\ndef my_reward_function(state, action, next_state):\n return -np.mean(action)\n\n\nenv = gym.make(\"LocoMujoco\", env_name=\"HumanoidTorque.run\", reward_type=\"custom\",\n reward_params=dict(reward_callback=my_reward_function))\n\n```\n\nLocoMuJoCo *natively* supports [MushroomRL](https://github.com/MushroomRL/mushroom-rl):\n\n```python\nimport numpy as np\nfrom loco_mujoco import LocoEnv\n\nenv = LocoEnv.make(\"HumanoidTorque.run\")\ndataset = env.create_dataset()\n```\n\nYou can find many more examples [here](examples).\n\nDetailed Tutorials are given in the [Documentation](https://loco-mujoco.readthedocs.io/).\n\n---\n## Citation\n```\n@inproceedings{alhafez2023b,\ntitle={LocoMuJoCo: A Comprehensive Imitation Learning Benchmark for Locomotion},\nauthor={Firas Al-Hafez and Guoping Zhao and Jan Peters and Davide Tateo},\nbooktitle={6th Robot Learning Workshop, NeurIPS},\nyear={2023}\n}\n```\n\n---\n## Credits \nBoth Unitree models were taken from the [MuJoCo menagerie](https://github.com/google-deepmind/mujoco_menagerie)\n\n\n\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Al-Hafez Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Imitation learning benchmark focusing on complex locomotion tasks using MuJoCo.",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/robfiras/loco-mujoco",
"Issues": "https://github.com/robfiras/loco-mujoco/issues",
"Repository": "https://github.com/robfiras/loco-mujoco"
},
"split_keywords": [
"imitation learning",
" reinforcement learning",
" locomotion"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "366bfe0ad7af1ebd12b246f4710aa21a5222bfaf4e0bcc31e1020908987867f0",
"md5": "1055a4ca7639c6ec5c4d8b1fcb241b72",
"sha256": "44776fdd4e4d504a4dc933c90f0ccc68816e91efb5ffb2bcea7d06dbc5daa940"
},
"downloads": -1,
"filename": "loco-mujoco-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "1055a4ca7639c6ec5c4d8b1fcb241b72",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29630635,
"upload_time": "2024-09-13T15:29:28",
"upload_time_iso_8601": "2024-09-13T15:29:28.429827Z",
"url": "https://files.pythonhosted.org/packages/36/6b/fe0ad7af1ebd12b246f4710aa21a5222bfaf4e0bcc31e1020908987867f0/loco-mujoco-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-13 15:29:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "robfiras",
"github_project": "loco-mujoco",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "mushroom-rl",
"specs": [
[
">=",
"1.10.0"
]
]
},
{
"name": "numpy",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "mujoco",
"specs": [
[
"==",
"2.3.7"
]
]
},
{
"name": "gymnasium",
"specs": []
},
{
"name": "dm_control",
"specs": [
[
"==",
"1.0.14"
]
]
},
{
"name": "pyyaml",
"specs": []
},
{
"name": "wget",
"specs": []
},
{
"name": "gitpython",
"specs": []
}
],
"lcname": "loco-mujoco"
}