<img align="left" width="80" src="./docs/source/figures/CARL_logo.png" alt="CARL">
# – The Benchmark Library
[](https://pypi.python.org/pypi/carl-bench)
[](https://github.com/automl/carl/actions/workflows/tests.yaml)
[](https://github.com/automl/carl/actions/workflows/docs.yaml)
[](https://github.com/psf/black)
CARL (context adaptive RL) provides highly configurable contextual extensions
to several well-known RL environments.
It's designed to test your agent's generalization capabilities
in all scenarios where intra-task generalization is important.
Feel free to check out our [paper](https://arxiv.org/abs/2110.02102) and our short [blog post](https://www.automl.org/carl-a-benchmark-to-study-generalization-in-reinforcement-learning/)!
## Benchmarks
Benchmarks include:
- [OpenAI gym classic control suite](https://gym.openai.com/envs/#classic_control) extended with several physics context features like gravity or friction
- [OpenAI gym Box2D](https://gym.openai.com/envs/#box2d) BipedalWalker, LunarLander and
CarRacing, each with their own modification possibilities like
new vehicles to race
- All [Brax locomotion environments](https://github.com/google/brax) with exposed internal features like joint strength or torso mass
- [Super Mario (TOAD-GAN)](https://github.com/Mawiszus/TOAD-GAN), a procedurally generated jump'n'run game with control
over level similarity
- [dm_control](https://github.com/deepmind/dm_control), environments based on the MuJoCo physics engine. The environments are extended with different context features.
For more information, check out our [documentation](https://automl.github.io/CARL/)!
## Installation
We recommend you use a virtual environment (e.g. Anaconda) to
install CARL and its dependencies. We recommend and test with python 3.9 under Linux.
First, clone our repository and install the basic requirements:
```bash
git clone https://github.com/automl/CARL.git --recursive
cd CARL
pip install .
```
This will only install the basic classic control environments, which should run on most operating systems. For the full set of environments, use the install options:
```bash
pip install -e .[box2d,brax,dm_control,mario,rna]
```
These may not be compatible with Windows systems. Box2D environment may need to be installed via conda on MacOS systems:
```bash
conda install -c conda-forge gym-box2d
```
In general, we test on Linux systems, but aim to keep the benchmark compatible with MacOS as much as possible.
RNA and Mario at this point, however, will not run on any operation system besides Linux.
To install ToadGAN for the Mario environment:
```bash
# System requirements
sudo apt install libfreetype6-dev xvfb
```
If you want to use RNA, please take a look at the associated [ReadME](carl/envs/rna/readme.md).
## CARL's Contextual Extension
CARL contextually extends the environment by making the context visible and configurable.
During training we therefore can encounter different contexts and train for generalization.
We exemplarily show how Brax' Fetch is extended and embedded by CARL.
Different instiations can be achieved by setting the context features to different values.
## Cite Us
If you use CARL in your research, please cite our paper on the benchmark:
```bibtex
@inproceedings { BenEim2023a,
author = {Carolin Benjamins and
Theresa Eimer and
Frederik Schubert and
Aditya Mohan and
Sebastian Döhler and
André Biedenkapp and
Bodo Rosenhahn and
Frank Hutter and
Marius Lindauer},
title = {Contextualize Me - The Case for Context in Reinforcement Learning},
journal = {Transactions on Machine Learning Research},
year = {2023},
}
```
## References
[OpenAI gym, Brockman et al., 2016. arXiv preprint arXiv:1606.01540](https://arxiv.org/pdf/1606.01540.pdf)
[Brax -- A Differentiable Physics Engine for Large Scale
Rigid Body Simulation, Freeman et al., NeurIPS 2021 (Dataset &
Benchmarking Track)](https://arxiv.org/pdf/2106.13281.pdf)
[TOAD-GAN: Coherent Style Level Generation from a Single Example,
Awiszus et al., AIIDE 2020](https://arxiv.org/pdf/2008.01531.pdf)
[dm_control: Software and Tasks for Continuous Control](https://arxiv.org/pdf/2006.12983.pdf)
## License
CARL falls under the Apache License 2.0 (see file 'LICENSE') as is permitted by all
work that we use. This includes CARLMario, which is not based on the Nintendo Game, but on
TOAD-GAN and TOAD-GUI running under an MIT license. They in turn make use of the Mario AI framework
(https://github.com/amidos2006/Mario-AI-Framework). This is not the original game but a replica,
explicitly built for research purposes and includes a copyright notice (https://github.com/amidos2006/Mario-AI-Framework#copyrights ).
Raw data
{
"_id": null,
"home_page": "https://www.automl.org/",
"name": "carl-bench",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "RL,Generalization,Context,Reinforcement Learning",
"author": "Carolin Benjamins, Theresa Eimer, Frederik Schubert, Andr\u00e9 Biedenkapp, Aditya Mohan, Sebastian D\u00f6hler",
"author_email": "benjamins@tnt.uni-hannover.de",
"download_url": "https://files.pythonhosted.org/packages/e4/83/db675b21b2f9b766261eed1410416d5fd03b07e6f3a0e6d921895d77a6a7/carl-bench-1.1.0.tar.gz",
"platform": "Linux",
"description": "<img align=\"left\" width=\"80\" src=\"./docs/source/figures/CARL_logo.png\" alt=\"CARL\">\n\n# \u2013 The Benchmark Library\n[](https://pypi.python.org/pypi/carl-bench)\n[](https://github.com/automl/carl/actions/workflows/tests.yaml)\n[](https://github.com/automl/carl/actions/workflows/docs.yaml)\n[](https://github.com/psf/black)\n\nCARL (context adaptive RL) provides highly configurable contextual extensions\nto several well-known RL environments.\nIt's designed to test your agent's generalization capabilities\nin all scenarios where intra-task generalization is important.\n\nFeel free to check out our [paper](https://arxiv.org/abs/2110.02102) and our short [blog post](https://www.automl.org/carl-a-benchmark-to-study-generalization-in-reinforcement-learning/)!\n\n## Benchmarks\nBenchmarks include:\n- [OpenAI gym classic control suite](https://gym.openai.com/envs/#classic_control) extended with several physics context features like gravity or friction\n\n- [OpenAI gym Box2D](https://gym.openai.com/envs/#box2d) BipedalWalker, LunarLander and\n CarRacing, each with their own modification possibilities like\n new vehicles to race\n\n- All [Brax locomotion environments](https://github.com/google/brax) with exposed internal features like joint strength or torso mass\n\n- [Super Mario (TOAD-GAN)](https://github.com/Mawiszus/TOAD-GAN), a procedurally generated jump'n'run game with control\n over level similarity\n\n- [dm_control](https://github.com/deepmind/dm_control), environments based on the MuJoCo physics engine. The environments are extended with different context features.\n\n\n\nFor more information, check out our [documentation](https://automl.github.io/CARL/)!\n\n\n## Installation\nWe recommend you use a virtual environment (e.g. Anaconda) to\ninstall CARL and its dependencies. We recommend and test with python 3.9 under Linux.\n\nFirst, clone our repository and install the basic requirements:\n```bash\ngit clone https://github.com/automl/CARL.git --recursive\ncd CARL\npip install .\n```\n\nThis will only install the basic classic control environments, which should run on most operating systems. For the full set of environments, use the install options:\n```bash\npip install -e .[box2d,brax,dm_control,mario,rna]\n```\n\nThese may not be compatible with Windows systems. Box2D environment may need to be installed via conda on MacOS systems:\n```bash\nconda install -c conda-forge gym-box2d\n```\n\nIn general, we test on Linux systems, but aim to keep the benchmark compatible with MacOS as much as possible.\nRNA and Mario at this point, however, will not run on any operation system besides Linux.\n\nTo install ToadGAN for the Mario environment:\n```bash\n# System requirements\nsudo apt install libfreetype6-dev xvfb\n```\n\nIf you want to use RNA, please take a look at the associated [ReadME](carl/envs/rna/readme.md).\n\n## CARL's Contextual Extension\nCARL contextually extends the environment by making the context visible and configurable.\nDuring training we therefore can encounter different contexts and train for generalization.\nWe exemplarily show how Brax' Fetch is extended and embedded by CARL.\nDifferent instiations can be achieved by setting the context features to different values.\n\n\n\n## Cite Us\nIf you use CARL in your research, please cite our paper on the benchmark:\n```bibtex\n@inproceedings { BenEim2023a,\n author = {Carolin Benjamins and\n Theresa Eimer and\n Frederik Schubert and\n Aditya Mohan and\n Sebastian D\u00f6hler and\n Andr\u00e9 Biedenkapp and\n Bodo Rosenhahn and\n Frank Hutter and\n Marius Lindauer},\n title = {Contextualize Me - The Case for Context in Reinforcement Learning},\n journal = {Transactions on Machine Learning Research},\n year = {2023},\n}\n\n```\n\n## References\n[OpenAI gym, Brockman et al., 2016. arXiv preprint arXiv:1606.01540](https://arxiv.org/pdf/1606.01540.pdf)\n\n[Brax -- A Differentiable Physics Engine for Large Scale\nRigid Body Simulation, Freeman et al., NeurIPS 2021 (Dataset &\nBenchmarking Track)](https://arxiv.org/pdf/2106.13281.pdf)\n\n[TOAD-GAN: Coherent Style Level Generation from a Single Example,\nAwiszus et al., AIIDE 2020](https://arxiv.org/pdf/2008.01531.pdf)\n\n[dm_control: Software and Tasks for Continuous Control](https://arxiv.org/pdf/2006.12983.pdf)\n\n## License\nCARL falls under the Apache License 2.0 (see file 'LICENSE') as is permitted by all\nwork that we use. This includes CARLMario, which is not based on the Nintendo Game, but on\nTOAD-GAN and TOAD-GUI running under an MIT license. They in turn make use of the Mario AI framework\n(https://github.com/amidos2006/Mario-AI-Framework). This is not the original game but a replica,\nexplicitly built for research purposes and includes a copyright notice (https://github.com/amidos2006/Mario-AI-Framework#copyrights ).\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "CARL- Contextually Adaptive Reinforcement Learning",
"version": "1.1.0",
"project_urls": {
"Documentation": "https://automl.github.io/CARL",
"Homepage": "https://www.automl.org/",
"Source Code": "https://github.com/https://github.com/automl/CARL"
},
"split_keywords": [
"rl",
"generalization",
"context",
"reinforcement learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e4f2d066269e227d96d6ba9f25a3529f3a10f13fd9746a3f36142002b1100df8",
"md5": "e2a63115fa5c25188bbebf305640109c",
"sha256": "cff8a61d50e3c4cec5b026f2f950e9b158335c09d1f9a65be4530d07b6fa8b3c"
},
"downloads": -1,
"filename": "carl_bench-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2a63115fa5c25188bbebf305640109c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 127382,
"upload_time": "2024-02-13T15:22:55",
"upload_time_iso_8601": "2024-02-13T15:22:55.034473Z",
"url": "https://files.pythonhosted.org/packages/e4/f2/d066269e227d96d6ba9f25a3529f3a10f13fd9746a3f36142002b1100df8/carl_bench-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e483db675b21b2f9b766261eed1410416d5fd03b07e6f3a0e6d921895d77a6a7",
"md5": "d02a5988751b34805d7ad8edcca6f099",
"sha256": "ab84b317099dfb5920638efc85733dc6944172ecbb1b5b9b2de57bab3ffa8dd1"
},
"downloads": -1,
"filename": "carl-bench-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d02a5988751b34805d7ad8edcca6f099",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 87272,
"upload_time": "2024-02-13T15:22:58",
"upload_time_iso_8601": "2024-02-13T15:22:58.099459Z",
"url": "https://files.pythonhosted.org/packages/e4/83/db675b21b2f9b766261eed1410416d5fd03b07e6f3a0e6d921895d77a6a7/carl-bench-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-13 15:22:58",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "carl-bench"
}
JSON