# AMP-RSL-RL
AMP-RSL-RL is a reinforcement learning library that extends the Proximal Policy Optimization (PPO) implementation of [RSL-RL](https://github.com/leggedrobotics/rsl_rl) to incorporate Adversarial Motion Priors (AMP). This framework enables humanoid agents to learn motor skills from motion capture data using adversarial imitation learning techniques.
---
## 📦 Installation
The repository is available on PyPI under the package name **amp-rl-rsl**. You can install it directly using pip:
```bash
pip install amp-rsl-rl
```
Alternatively, if you prefer to clone the repository and install it locally, follow these steps:
1. Clone the repository:
```bash
git clone https://github.com/<your-username>/amp_rsl_rl.git
cd amp_rsl_rl
```
2. Install the package:
```bash
pip install .
```
For editable/development mode:
```bash
pip install -e .
```
If you want to run the examples, please install with:
```bash
pip install .[examples]
```
The required dependencies include:
- `numpy`
- `scipy`
- `torch`
- `rsl-rl-lib`
These will be automatically installed via pip.
---
## 📂 Project Structure
```
amp_rsl_rl/
│
├── algorithms/ # AMP and PPO implementations
├── networks/ # Neural networks for policy and discriminator
├── runners/ # Training and evaluation routines
├── storage/ # Replay buffer for experience collection
├── utils/ # Dataset loaders and motion tools
```
---
## 📁 Dataset Structure
The AMP-RSL-RL framework expects motion capture datasets in `.npy` format. Each `.npy` file must contain a Python dictionary with the following keys:
- **`joints_list`**: `List[str]`
A list of joint names. These should correspond to the joint order expected by the agent.
- **`joint_positions`**: `List[np.ndarray]`
A list where each element is a NumPy array representing the joint positions at a frame. All arrays should have the same shape `(N,)`, where `N` is the number of joints.
- **`root_position`**: `List[np.ndarray]`
A list of 3D vectors representing the position of the base (root) of the agent in world coordinates for each frame.
- **`root_quaternion`**: `List[np.ndarray]`
A list of unit quaternions in **`xyzw`** format (SciPy convention), representing the base orientation of the agent for each frame.
- **`fps`**: `float`
The number of frames per second in the original dataset. This is used to resample the data to match the simulator's timestep.
### Example
Here’s an example of how the structure might look when loaded in Python:
```python
{
"joints_list": ["hip", "knee", "ankle"],
"joint_positions": [np.array([0.1, -0.2, 0.3]), np.array([0.11, -0.21, 0.31]), ...],
"root_position": [np.array([0.0, 0.0, 1.0]), np.array([0.01, 0.0, 1.0]), ...],
"root_quaternion": [np.array([0.0, 0.0, 0.0, 1.0]), np.array([0.0, 0.0, 0.1, 0.99]), ...],
"fps": 120.0
}
```
All lists must have the same number of entries (i.e. one per frame). The dataset should represent smooth motion captured over time.
---
## 📚 Supported Dataset
For a ready-to-use motion capture dataset, you can use the [AMP Dataset on Hugging Face](https://huggingface.co/datasets/ami-iit/amp-dataset). This dataset is curated to work seamlessly with the AMP-RSL-RL framework.
---
## 🧑💻 Authors
- **Giulio Romualdi** – [@GiulioRomualdi](https://github.com/GiulioRomualdi)
- **Giuseppe L'Erario** – [@Giulero](https://github.com/Giulero)
---
## 📄 License
BSD 3-Clause License © 2025 Istituto Italiano di Tecnologia
Raw data
{
"_id": null,
"home_page": null,
"name": "amp-rsl-rl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Giulio Romualdi <giulio.romualdi@iit.it>, Giuseppe L'Erario <giuseppe.lerario@iit.it>",
"keywords": "reinforcement-learning, robotics, motion-priors, ppo",
"author": null,
"author_email": "Giulio Romualdi <giulio.romualdi@iit.it>, Giuseppe L'Erario <giuseppe.lerario@iit.it>",
"download_url": "https://files.pythonhosted.org/packages/8e/ac/8c9550b6cb6734d20f441c6d4690eb18f72e74f86e50eee7a6ad5800e919/amp_rsl_rl-0.2.8.tar.gz",
"platform": null,
"description": "# AMP-RSL-RL\n\nAMP-RSL-RL is a reinforcement learning library that extends the Proximal Policy Optimization (PPO) implementation of [RSL-RL](https://github.com/leggedrobotics/rsl_rl) to incorporate Adversarial Motion Priors (AMP). This framework enables humanoid agents to learn motor skills from motion capture data using adversarial imitation learning techniques.\n\n---\n\n## \ud83d\udce6 Installation\n\nThe repository is available on PyPI under the package name **amp-rl-rsl**. You can install it directly using pip:\n\n```bash\npip install amp-rsl-rl\n```\n\nAlternatively, if you prefer to clone the repository and install it locally, follow these steps:\n\n1. Clone the repository:\n ```bash\n git clone https://github.com/<your-username>/amp_rsl_rl.git\n cd amp_rsl_rl\n ```\n\n2. Install the package:\n ```bash\n pip install .\n ```\n\nFor editable/development mode:\n\n```bash\npip install -e .\n```\n\nIf you want to run the examples, please install with:\n\n```bash\npip install .[examples]\n```\n\nThe required dependencies include:\n\n- `numpy`\n- `scipy`\n- `torch`\n- `rsl-rl-lib`\n\nThese will be automatically installed via pip.\n\n---\n\n## \ud83d\udcc2 Project Structure\n\n```\namp_rsl_rl/\n\u2502\n\u251c\u2500\u2500 algorithms/ # AMP and PPO implementations\n\u251c\u2500\u2500 networks/ # Neural networks for policy and discriminator\n\u251c\u2500\u2500 runners/ # Training and evaluation routines\n\u251c\u2500\u2500 storage/ # Replay buffer for experience collection\n\u251c\u2500\u2500 utils/ # Dataset loaders and motion tools\n```\n\n---\n\n## \ud83d\udcc1 Dataset Structure\n\nThe AMP-RSL-RL framework expects motion capture datasets in `.npy` format. Each `.npy` file must contain a Python dictionary with the following keys:\n\n- **`joints_list`**: `List[str]` \n A list of joint names. These should correspond to the joint order expected by the agent.\n\n- **`joint_positions`**: `List[np.ndarray]` \n A list where each element is a NumPy array representing the joint positions at a frame. All arrays should have the same shape `(N,)`, where `N` is the number of joints.\n\n- **`root_position`**: `List[np.ndarray]` \n A list of 3D vectors representing the position of the base (root) of the agent in world coordinates for each frame.\n\n- **`root_quaternion`**: `List[np.ndarray]` \n A list of unit quaternions in **`xyzw`** format (SciPy convention), representing the base orientation of the agent for each frame.\n\n- **`fps`**: `float` \n The number of frames per second in the original dataset. This is used to resample the data to match the simulator's timestep.\n\n### Example\n\nHere\u2019s an example of how the structure might look when loaded in Python:\n\n```python\n{\n \"joints_list\": [\"hip\", \"knee\", \"ankle\"],\n \"joint_positions\": [np.array([0.1, -0.2, 0.3]), np.array([0.11, -0.21, 0.31]), ...],\n \"root_position\": [np.array([0.0, 0.0, 1.0]), np.array([0.01, 0.0, 1.0]), ...],\n \"root_quaternion\": [np.array([0.0, 0.0, 0.0, 1.0]), np.array([0.0, 0.0, 0.1, 0.99]), ...],\n \"fps\": 120.0\n}\n```\n\nAll lists must have the same number of entries (i.e. one per frame). The dataset should represent smooth motion captured over time.\n\n---\n\n## \ud83d\udcda Supported Dataset\n\nFor a ready-to-use motion capture dataset, you can use the [AMP Dataset on Hugging Face](https://huggingface.co/datasets/ami-iit/amp-dataset). This dataset is curated to work seamlessly with the AMP-RSL-RL framework.\n\n---\n\n## \ud83e\uddd1\u200d\ud83d\udcbb Authors\n\n- **Giulio Romualdi** \u2013 [@GiulioRomualdi](https://github.com/GiulioRomualdi)\n- **Giuseppe L'Erario** \u2013 [@Giulero](https://github.com/Giulero)\n\n---\n\n## \ud83d\udcc4 License\n\nBSD 3-Clause License \u00a9 2025 Istituto Italiano di Tecnologia\n",
"bugtrack_url": null,
"license": null,
"summary": "Adversarial Motion Prior (AMP) reinforcement learning extension for PPO based on RSL-RL.",
"version": "0.2.8",
"project_urls": {
"BugTracker": "https://github.com/ami-iit/amp-rsl-rl/issues",
"Changelog": "https://github.com/ami-iit/amp-rsl-rl/releases",
"Homepage": "https://github.com/ami-iit/amp-rsl-rl",
"Repository": "https://github.com/ami-iit/amp-rsl-rl"
},
"split_keywords": [
"reinforcement-learning",
" robotics",
" motion-priors",
" ppo"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5629933944962e18e86c46f6348447b06003cd850173be237f72f6e58da6bd14",
"md5": "4603f809791887958964037a98d2e0cb",
"sha256": "48c8a6448316a3ca1bca388dae24d096d776a5a5850f081727dc93d48d5dc7b5"
},
"downloads": -1,
"filename": "amp_rsl_rl-0.2.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4603f809791887958964037a98d2e0cb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 33608,
"upload_time": "2025-08-04T08:27:42",
"upload_time_iso_8601": "2025-08-04T08:27:42.637755Z",
"url": "https://files.pythonhosted.org/packages/56/29/933944962e18e86c46f6348447b06003cd850173be237f72f6e58da6bd14/amp_rsl_rl-0.2.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8eac8c9550b6cb6734d20f441c6d4690eb18f72e74f86e50eee7a6ad5800e919",
"md5": "845e96e9b885c74c2799c17962c545cc",
"sha256": "519bca839bba6428750409eb82bf7fc15631a5a8c30a8efe98fe377f0bdd54ec"
},
"downloads": -1,
"filename": "amp_rsl_rl-0.2.8.tar.gz",
"has_sig": false,
"md5_digest": "845e96e9b885c74c2799c17962c545cc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 35949,
"upload_time": "2025-08-04T08:27:43",
"upload_time_iso_8601": "2025-08-04T08:27:43.789429Z",
"url": "https://files.pythonhosted.org/packages/8e/ac/8c9550b6cb6734d20f441c6d4690eb18f72e74f86e50eee7a6ad5800e919/amp_rsl_rl-0.2.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 08:27:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ami-iit",
"github_project": "amp-rsl-rl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "amp-rsl-rl"
}
JSON
