| Name | relab JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | https://github.com/TheophileChampion/ReLab/ |
| Summary | Reinforcement learning made easy with prebuilt agents, Gym integration, and performance visualization. |
| upload_time | 2025-02-01 17:02:37 |
| maintainer | None |
| docs_url | None |
| author | Théophile Champion |
| requires_python | <4.0,>=3.12 |
| license | MIT License
Copyright (c) 2025 Théophile Champion
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 |
pytorch
reinforcement learning
deep learning
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 
---
ReLab is a powerful and user-friendly library designed to streamline
reinforcement learning experiments. With a curated collection of well-known
RL agents and seamless integration with Gym environments, ReLab empowers you
to train agents effortlessly, visualize their learned behaviors, and compare
their performance across diverse metrics. Whether you're a researcher exploring
state-of-the-art algorithms or a practitioner fine-tuning agents for real-world
applications, ReLab simplifies the process, saving you time and effort.
<!-- toc -->
- [Installation](#installation)
- [Clone the ReLab source code](#clone-the-relab-source-code)
- [Download ReLab dependencies](#download-relab-dependencies)
- [Ensure that python scripts can find the ReLab package](#ensure-that-python-scripts-can-find-the-relab-package)
- [Check that the installation was successful](#check-that-the-installation-was-successful)
- [Getting Started](#getting-started)
- [Documentation](#documentation)
- [Releases and Contributing](#releases-and-contributing)
- [License](#license)
<!-- tocstop -->
## Installation
### Clone the ReLab source code
```console
git clone git@github.com:TheophileChampion/ReLab.git
cd ReLab
```
### Download ReLab dependencies
```console
python3.12 -m venv venv-relab
source ./venv-relab/bin/activate
pip install -r requirements.txt
```
### Ensure that python scripts can find the ReLab package
```console
pwd > ./venv-relab/lib/python3.12/site-packages/relab.pth
```
### Check that the installation was successful
```console
python ./scripts/test_install
```
Note, when running the above command for the first time, ReLab will compile its C++ library.
## ReLab Fundamentals
ReLab provides a collection of well-known reinforcement learning agents and enables you to train them on any [Gym](https://gymnasium.farama.org/) environment.
You can then visualize the learned policies and compare the performance of various agents.
Before proceeding with the following sections, make sure that ReLab is [installed](#installation) and activate the virtual environment using the following command:
```console
source ./venv-relab/bin/activate
```
### Training an Agent
An agent can be trained by running the following command:
```console
python ./scripts/run_training --agent DQN --env ALE/Pong-v5 --seed 0
```
The training script accepts three parameters:
- `--agent` specifies the reinforcement learning agent to train,
- `--env` defines the environment in which the agent will be trained, and
- `--seed` sets the random seed to ensure reproducibility.
As the agent is learning, you can visualize its performance using the following command:
```console
tensorboard --logdir=./data/runs/
```
This will open a graphical interface at <http://localhost:6006/>, allowing you to monitor:
- the agent's mean episodic reward,
- the training speed (in milliseconds per training iteration), and
- the memory usage of the training script.
### Visualizing a Learned Policy
By default, ReLab saves the learned policy every 500,000 training iterations.
Once an agent has been trained, you can visualize its learned policy using the following command:
```console
python ./scripts/run_demo --agent DQN --env ALE/Pong-v5 --seed 0
```
These parameters should look familiar, as they are identical to those used in the training script.
By default, ReLab demonstrates the latest policy.
However, you can specify a particular model checkpoint using the following command:
```console
python ./scripts/run_demo --agent DQN --env ALE/Pong-v5 --seed 0 --index 1000000
```
Here, the `--index` parameter allows you to select the policy learned by the agent after 1,000,000 training iterations.
After running the above command, ReLab will generate a GIF of the agent's behavior, which can be found in:
```console
./data/demos/Pong-v5/DQN/0/demo_1000000.gif
```
<img alt="PrioritizedDDQN playing the Atari game Pong." width="500" height="300" src="https://github.com/TheophileChampion/ReLab/tree/main/assets/demo_prioritized_ddqn_pong.gif">
### Comparing the Performance of Various Agents
ReLab also provides a script to generate graphs summarizing the agent performance:
```console
python ./scripts/draw_graph --agents DQN --env ALE/Pong-v5 --seeds 0 --metric mean_episodic_reward
```
Importantly, the parameters `--agents` and `--seeds` are now plural because the script accepts a list of agents and seeds.
The `--metric` parameter allows you to compare agents based on various metrics, such as episodic mean reward, training speed, or memory usage.
This script can also be used to compare multiple agents across different seeds, as shown below:
```console
python ./scripts/draw_graph --agents DQN RainbowDQN --env ALE/Pong-v5 --seeds 0 1 2 3 4 --metric mean_episodic_reward
```
When multiple seeds are provided, the graph will display a solid line representing the average metric, along with a shaded area indicating the metric's standard deviation.
<img alt="Graph comparing the performance of several agents." src="https://github.com/TheophileChampion/ReLab/tree/main/assets/mean_episodic_reward.png" width="500"/>
For a deeper dive into advanced use cases of ReLab and additional examples, check out our [In-Depth Tutorial](https://theophilechampion.github.io/ReLab/md_Tutorial.html).
## Documentation
ReLab [documentation](https://theophilechampion.github.io/ReLab/) is based on doxygen and hosted with GitHub Pages.
## Releases and Contributing
Please let us know if you encounter a bug by [filing an issue](https://github.com/TheophileChampion/ReLab/issues).
ReLab follows a "fork and pull request" workflow. If you are planning to contribute, you must:
- Fork ReLab to your GitHub account
- Clone your fork on your computer
- Create a new branch to work on
- Make changes and commit them with a clear description
- Push your branch to your forked GitHub repository
- Open a pull request to the ReLab project
ReLab is still in beta. The latest version of ReLab is version 1.0.0-b.
## License
ReLab has a MIT license, as found in the [license](https://github.com/TheophileChampion/ReLab/blob/main/LICENSE.md) file.
Raw data
{
"_id": null,
"home_page": "https://github.com/TheophileChampion/ReLab/",
"name": "relab",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": "pytorch, reinforcement learning, deep learning",
"author": "Th\u00e9ophile Champion",
"author_email": "theoph.champion@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e6/d0/600bf982914208c160f8829b808fa80533a51895a757b935856d32e900a8/relab-0.5.0.tar.gz",
"platform": null,
"description": "# \n\n---\n\nReLab is a powerful and user-friendly library designed to streamline\nreinforcement learning experiments. With a curated collection of well-known\nRL agents and seamless integration with Gym environments, ReLab empowers you\nto train agents effortlessly, visualize their learned behaviors, and compare\ntheir performance across diverse metrics. Whether you're a researcher exploring\nstate-of-the-art algorithms or a practitioner fine-tuning agents for real-world\napplications, ReLab simplifies the process, saving you time and effort.\n\n<!-- toc -->\n\n- [Installation](#installation)\n - [Clone the ReLab source code](#clone-the-relab-source-code)\n - [Download ReLab dependencies](#download-relab-dependencies)\n - [Ensure that python scripts can find the ReLab package](#ensure-that-python-scripts-can-find-the-relab-package)\n - [Check that the installation was successful](#check-that-the-installation-was-successful)\n- [Getting Started](#getting-started)\n- [Documentation](#documentation)\n- [Releases and Contributing](#releases-and-contributing)\n- [License](#license)\n<!-- tocstop -->\n\n## Installation\n\n### Clone the ReLab source code\n\n```console\ngit clone git@github.com:TheophileChampion/ReLab.git\ncd ReLab\n```\n\n### Download ReLab dependencies\n\n```console\npython3.12 -m venv venv-relab\nsource ./venv-relab/bin/activate\npip install -r requirements.txt\n```\n\n### Ensure that python scripts can find the ReLab package\n\n```console\npwd > ./venv-relab/lib/python3.12/site-packages/relab.pth\n```\n\n### Check that the installation was successful\n\n```console\npython ./scripts/test_install\n```\n\nNote, when running the above command for the first time, ReLab will compile its C++ library.\n\n## ReLab Fundamentals\n\nReLab provides a collection of well-known reinforcement learning agents and enables you to train them on any [Gym](https://gymnasium.farama.org/) environment.\nYou can then visualize the learned policies and compare the performance of various agents.\nBefore proceeding with the following sections, make sure that ReLab is [installed](#installation) and activate the virtual environment using the following command:\n\n```console\nsource ./venv-relab/bin/activate\n```\n\n### Training an Agent\n\nAn agent can be trained by running the following command:\n\n```console\npython ./scripts/run_training --agent DQN --env ALE/Pong-v5 --seed 0\n```\n\nThe training script accepts three parameters:\n\n- `--agent` specifies the reinforcement learning agent to train,\n- `--env` defines the environment in which the agent will be trained, and\n- `--seed` sets the random seed to ensure reproducibility.\n\nAs the agent is learning, you can visualize its performance using the following command:\n\n```console\ntensorboard --logdir=./data/runs/\n```\n\nThis will open a graphical interface at <http://localhost:6006/>, allowing you to monitor:\n\n- the agent's mean episodic reward,\n- the training speed (in milliseconds per training iteration), and\n- the memory usage of the training script.\n\n### Visualizing a Learned Policy\n\nBy default, ReLab saves the learned policy every 500,000 training iterations.\nOnce an agent has been trained, you can visualize its learned policy using the following command:\n\n```console\npython ./scripts/run_demo --agent DQN --env ALE/Pong-v5 --seed 0\n```\n\nThese parameters should look familiar, as they are identical to those used in the training script.\nBy default, ReLab demonstrates the latest policy.\nHowever, you can specify a particular model checkpoint using the following command:\n\n```console\npython ./scripts/run_demo --agent DQN --env ALE/Pong-v5 --seed 0 --index 1000000\n```\n\nHere, the `--index` parameter allows you to select the policy learned by the agent after 1,000,000 training iterations.\nAfter running the above command, ReLab will generate a GIF of the agent's behavior, which can be found in:\n\n```console\n./data/demos/Pong-v5/DQN/0/demo_1000000.gif\n```\n\n<img alt=\"PrioritizedDDQN playing the Atari game Pong.\" width=\"500\" height=\"300\" src=\"https://github.com/TheophileChampion/ReLab/tree/main/assets/demo_prioritized_ddqn_pong.gif\">\n\n### Comparing the Performance of Various Agents\n\nReLab also provides a script to generate graphs summarizing the agent performance:\n\n```console\npython ./scripts/draw_graph --agents DQN --env ALE/Pong-v5 --seeds 0 --metric mean_episodic_reward\n```\n\nImportantly, the parameters `--agents` and `--seeds` are now plural because the script accepts a list of agents and seeds.\nThe `--metric` parameter allows you to compare agents based on various metrics, such as episodic mean reward, training speed, or memory usage.\nThis script can also be used to compare multiple agents across different seeds, as shown below:\n\n```console\npython ./scripts/draw_graph --agents DQN RainbowDQN --env ALE/Pong-v5 --seeds 0 1 2 3 4 --metric mean_episodic_reward\n```\n\nWhen multiple seeds are provided, the graph will display a solid line representing the average metric, along with a shaded area indicating the metric's standard deviation.\n\n<img alt=\"Graph comparing the performance of several agents.\" src=\"https://github.com/TheophileChampion/ReLab/tree/main/assets/mean_episodic_reward.png\" width=\"500\"/>\n\nFor a deeper dive into advanced use cases of ReLab and additional examples, check out our [In-Depth Tutorial](https://theophilechampion.github.io/ReLab/md_Tutorial.html).\n\n## Documentation\n\nReLab [documentation](https://theophilechampion.github.io/ReLab/) is based on doxygen and hosted with GitHub Pages.\n\n## Releases and Contributing\n\nPlease let us know if you encounter a bug by [filing an issue](https://github.com/TheophileChampion/ReLab/issues).\n\nReLab follows a \"fork and pull request\" workflow. If you are planning to contribute, you must:\n\n- Fork ReLab to your GitHub account\n- Clone your fork on your computer\n- Create a new branch to work on\n- Make changes and commit them with a clear description\n- Push your branch to your forked GitHub repository\n- Open a pull request to the ReLab project\n\nReLab is still in beta. The latest version of ReLab is version 1.0.0-b.\n\n## License\n\nReLab has a MIT license, as found in the [license](https://github.com/TheophileChampion/ReLab/blob/main/LICENSE.md) file.\n",
"bugtrack_url": null,
"license": "MIT License\n\nCopyright (c) 2025 Th\u00e9ophile Champion\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n",
"summary": "Reinforcement learning made easy with prebuilt agents, Gym integration, and performance visualization.",
"version": "0.5.0",
"project_urls": {
"Documentation": "https://theophilechampion.github.io/ReLab/",
"Homepage": "https://github.com/TheophileChampion/ReLab/",
"Repository": "https://github.com/TheophileChampion/ReLab/"
},
"split_keywords": [
"pytorch",
" reinforcement learning",
" deep learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "de86770e7f4b3926ef04e8d376be915b1327d7e5dbeb5339828c28c9aebf606b",
"md5": "d0b78adac2e7f4d4836142688262f357",
"sha256": "51a4727888d44142124f775eb7fd95e3814e053bccd9ec53e2b8642171dd73ab"
},
"downloads": -1,
"filename": "relab-0.5.0-cp312-cp312-manylinux_2_39_x86_64.whl",
"has_sig": false,
"md5_digest": "d0b78adac2e7f4d4836142688262f357",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": "<4.0,>=3.12",
"size": 408413,
"upload_time": "2025-02-01T17:02:34",
"upload_time_iso_8601": "2025-02-01T17:02:34.628871Z",
"url": "https://files.pythonhosted.org/packages/de/86/770e7f4b3926ef04e8d376be915b1327d7e5dbeb5339828c28c9aebf606b/relab-0.5.0-cp312-cp312-manylinux_2_39_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e6d0600bf982914208c160f8829b808fa80533a51895a757b935856d32e900a8",
"md5": "947450fa77491f00062fcb62c968a97f",
"sha256": "98f5bc2e54520d3e9c97f8df9ba5cc828c8764cc3dee9ea2dfb8fbb0b0f95e6b"
},
"downloads": -1,
"filename": "relab-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "947450fa77491f00062fcb62c968a97f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 97567,
"upload_time": "2025-02-01T17:02:37",
"upload_time_iso_8601": "2025-02-01T17:02:37.375250Z",
"url": "https://files.pythonhosted.org/packages/e6/d0/600bf982914208c160f8829b808fa80533a51895a757b935856d32e900a8/relab-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-01 17:02:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TheophileChampion",
"github_project": "ReLab",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "relab"
}
