[](https://www.python.org/downloads/)
[](https://github.com/gymprecice/gymprecice/blob/master/LICENSE.md)
[](https://github.com/psf/black)
[](https://github.com/gymprecice/gymprecice/actions/workflows/pre-commit.yml)
[](https://github.com/gymprecice/gymprecice/actions/workflows/build-and-test.yml)
## Gym-preCICE
Gym-preCICE is a Python [preCICE](https://precice.org/) adapter fully compliant with [Gymnasium](https://gymnasium.farama.org/) (also known as [OpenAI Gym](https://www.gymlibrary.dev/)) API to facilitate designing and developing Reinforcement Learning (RL) environments for single- and multi-physics active flow control (AFC) applications. In an actor-environment setting, Gym-preCICE takes advantage of preCICE, an open-source coupling library for partitioned multi-physics simulations, to handle information exchange between a controller (actor) and an AFC simulation environment. The developed framework results in a seamless non-invasive integration of realistic physics-based simulation toolboxes with RL algorithms.
## Installation
### Main required dependencies
**Gymnasium**: Installed by default. Refer to [the Gymnasium](https://gymnasium.farama.org/) for more information.
**preCICE**: You need to install the preCICE library. Refer to [the preCICE documentation](https://precice.org/installation-overview.html) for information on building and installation.
**preCICE Python bindings**: Installed by default. Refer to [the python language bindings for preCICE](https://github.com/precice/python-bindings) for information.
### Installing the package
We support and test for Python versions 3.7 and higher on Linux. We recommend installing Gym-preCICE within a virtual environment, e.g. [conda](https://www.anaconda.com/products/distribution#Downloads):
- create and activate a conda virtual environment:
```bash
conda create -n gymprecice python=3.8
conda activate gymprecice
```
#### PIP version
- install the adapter:
```bash
python3 -m pip install gymprecice
```
- run a simple test to check `gymprecice` installation (this should pass silently without any error/warning messages):
```bash
python3 -c "import gymprecice"
```
The default installation does not include extra dependencies to run tests or tutorials. You can install these dependencies like `python3 -m pip install gymprecice[test]`, or
`python3 -m pip install gymprecice[tutorial]`, or use `python3 -m pip install gymprecice[all]` to install all extra dependencies.
#### Development version
- if you are contributing a pull request, it is best to install from the source:
```bash
git clone https://github.com/gymprecice/gymprecice.git
cd gymprecice
pip install -e .
pip install -e .[dev]
pre-commit install
```
### Testing
We use `pytest` framework to run unit tests for all modules in our package. You need to install required dependencies before running any test:
```bash
python3 -m pip install gymprecice[test]
```
- To run the full test suits:
```
pytest ./tests
```
- To run a specific unit test, e.g. to test core module (`core.py`):
```
pytest ./tests/test_core.py
```
### Usage
Please refer to [tutorials](https://github.com/gymprecice/tutorials) for the details on how to use the adapter. You can check out the [Quickstart](https://github.com/gymprecice/tutorials/tree/main/quickstart) in our [tutorials](https://github.com/gymprecice/tutorials) repository to try a ready-to-run control case. You need to install some of the required dependencies before running any tutorial:
```bash
python3 -m pip install gymprecice[tutorial]
```
## Citing Us
If you use Gym-preCICE, please cite the following paper:
```
@misc{shams2023gymprecice,
title={Gym-preCICE: Reinforcement Learning Environments for Active Flow Control},
author={Mosayeb Shams and Ahmed H. Elsheikh},
year={2023},
eprint={2305.02033},
archivePrefix={arXiv}
}
```
## Contributing
See the contributing guidelines [CONTRIBUTING.md](https://github.com/gymprecice/gymprecice/blob/main/CONTRIBUTING.md)
for information on submitting issues and pull requests.
## The Team
Gym-preCICE and its tutorials are primarily developed and maintained by:
- Mosayeb Shams (@mosayebshams) - Lead Developer (Heriot-Watt University)
- Ahmed H. Elsheikh(@ahmed-h-elsheikh) - Supervisor (Heriot-Watt University)
## Acknowledgements
This work was supported by the Engineering and Physical Sciences Research Council grant number EP/V048899/1.
## License
Gym-preCICE and its tutorials are [MIT licensed](https://github.com/gymprecice/gymprecice/blob/main/LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/gymprecice/gymprecice/",
"name": "gymprecice",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "Reinforcement Learning,RL,Deep Reinforcement Learning,DRL,AI,Gymnasium,OpenAI Gym,preCICE,Active Flow Control",
"author": "Mosayeb Shams (lead-developer), Ahmed. H. Elsheikh (supervisor)",
"author_email": "\"Mosayeb Shams (lead developer)\" <m.shams@hw.ac.uk>, \"Ahmed H. Elsheikh (supervisor)\" <a.elsheikh@hw.ac.uk>",
"download_url": "https://files.pythonhosted.org/packages/d4/f1/62fc43728d44a931f5c1c553591c7b7bc2ac7ee812006d9ec428a96d4ad3/gymprecice-0.1.0.tar.gz",
"platform": null,
"description": "[](https://www.python.org/downloads/)\n[](https://github.com/gymprecice/gymprecice/blob/master/LICENSE.md)\n[](https://github.com/psf/black)\n[](https://github.com/gymprecice/gymprecice/actions/workflows/pre-commit.yml)\n[](https://github.com/gymprecice/gymprecice/actions/workflows/build-and-test.yml)\n\n\n## Gym-preCICE\n\nGym-preCICE is a Python [preCICE](https://precice.org/) adapter fully compliant with [Gymnasium](https://gymnasium.farama.org/) (also known as [OpenAI Gym](https://www.gymlibrary.dev/)) API to facilitate designing and developing Reinforcement Learning (RL) environments for single- and multi-physics active flow control (AFC) applications. In an actor-environment setting, Gym-preCICE takes advantage of preCICE, an open-source coupling library for partitioned multi-physics simulations, to handle information exchange between a controller (actor) and an AFC simulation environment. The developed framework results in a seamless non-invasive integration of realistic physics-based simulation toolboxes with RL algorithms.\n\n\n## Installation\n\n### Main required dependencies\n\n**Gymnasium**: Installed by default. Refer to [the Gymnasium](https://gymnasium.farama.org/) for more information.\n\n**preCICE**: You need to install the preCICE library. Refer to [the preCICE documentation](https://precice.org/installation-overview.html) for information on building and installation.\n\n**preCICE Python bindings**: Installed by default. Refer to [the python language bindings for preCICE](https://github.com/precice/python-bindings) for information.\n\n\n### Installing the package\n\nWe support and test for Python versions 3.7 and higher on Linux. We recommend installing Gym-preCICE within a virtual environment, e.g. [conda](https://www.anaconda.com/products/distribution#Downloads):\n\n- create and activate a conda virtual environment:\n```bash\n conda create -n gymprecice python=3.8\n conda activate gymprecice\n```\n\n\n#### PIP version\n- install the adapter:\n\n```bash\npython3 -m pip install gymprecice\n```\n- run a simple test to check `gymprecice` installation (this should pass silently without any error/warning messages):\n```bash\npython3 -c \"import gymprecice\"\n```\n\nThe default installation does not include extra dependencies to run tests or tutorials. You can install these dependencies like `python3 -m pip install gymprecice[test]`, or\n`python3 -m pip install gymprecice[tutorial]`, or use `python3 -m pip install gymprecice[all]` to install all extra dependencies.\n\n#### Development version\n- if you are contributing a pull request, it is best to install from the source:\n```bash\ngit clone https://github.com/gymprecice/gymprecice.git\ncd gymprecice\npip install -e .\npip install -e .[dev]\npre-commit install\n```\n\n### Testing\n\nWe use `pytest` framework to run unit tests for all modules in our package. You need to install required dependencies before running any test:\n```bash\npython3 -m pip install gymprecice[test]\n```\n- To run the full test suits:\n```\npytest ./tests\n```\n- To run a specific unit test, e.g. to test core module (`core.py`):\n```\npytest ./tests/test_core.py\n```\n\n\n### Usage\n\nPlease refer to [tutorials](https://github.com/gymprecice/tutorials) for the details on how to use the adapter. You can check out the [Quickstart](https://github.com/gymprecice/tutorials/tree/main/quickstart) in our [tutorials](https://github.com/gymprecice/tutorials) repository to try a ready-to-run control case. You need to install some of the required dependencies before running any tutorial:\n```bash\npython3 -m pip install gymprecice[tutorial]\n```\n\n\n## Citing Us\n\nIf you use Gym-preCICE, please cite the following paper:\n\n```\n@misc{shams2023gymprecice,\n title={Gym-preCICE: Reinforcement Learning Environments for Active Flow Control},\n author={Mosayeb Shams and Ahmed H. Elsheikh},\n year={2023},\n eprint={2305.02033},\n archivePrefix={arXiv}\n}\n```\n\n## Contributing\n\nSee the contributing guidelines [CONTRIBUTING.md](https://github.com/gymprecice/gymprecice/blob/main/CONTRIBUTING.md)\nfor information on submitting issues and pull requests.\n\n\n## The Team\n\nGym-preCICE and its tutorials are primarily developed and maintained by:\n- Mosayeb Shams (@mosayebshams) - Lead Developer (Heriot-Watt University)\n- Ahmed H. Elsheikh(@ahmed-h-elsheikh) - Supervisor (Heriot-Watt University)\n\n\n## Acknowledgements\n\nThis work was supported by the Engineering and Physical Sciences Research Council grant number EP/V048899/1.\n\n\n## License\n\nGym-preCICE and its tutorials are [MIT licensed](https://github.com/gymprecice/gymprecice/blob/main/LICENSE).\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A framework to designe Reinforcement Learning (RL) environments for Active Flow Control (AFC), as well as a playground to train Deep Reinforcement Learning (DRL) algorithms for AFC applications.",
"version": "0.1.0",
"project_urls": {
"Bug Report": "https://github.com/gymprecice/gymprecice/issues",
"Homepage": "https://github.com/gymprecice",
"Repository": "https://github.com/gymprecice/gymprecice"
},
"split_keywords": [
"reinforcement learning",
"rl",
"deep reinforcement learning",
"drl",
"ai",
"gymnasium",
"openai gym",
"precice",
"active flow control"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3837aa7c3be6dbc1f525c334241f3527f66e6db8a5125abd8f103074639a4394",
"md5": "ea7c8c41e82c4caa8cff8a7a8d870dfd",
"sha256": "06352456ac2376d196c1fef673fe6d96ad4b399610302ed7afa1594a5a9f9285"
},
"downloads": -1,
"filename": "gymprecice-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ea7c8c41e82c4caa8cff8a7a8d870dfd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 21340,
"upload_time": "2023-05-04T12:46:25",
"upload_time_iso_8601": "2023-05-04T12:46:25.057697Z",
"url": "https://files.pythonhosted.org/packages/38/37/aa7c3be6dbc1f525c334241f3527f66e6db8a5125abd8f103074639a4394/gymprecice-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d4f162fc43728d44a931f5c1c553591c7b7bc2ac7ee812006d9ec428a96d4ad3",
"md5": "889559256d8795a489ced55251f2d706",
"sha256": "5c44f45e2b26f38f06dc94211f5da5f97ba089da4df6284a54f30678407954e6"
},
"downloads": -1,
"filename": "gymprecice-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "889559256d8795a489ced55251f2d706",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 22985,
"upload_time": "2023-05-04T12:46:26",
"upload_time_iso_8601": "2023-05-04T12:46:26.890160Z",
"url": "https://files.pythonhosted.org/packages/d4/f1/62fc43728d44a931f5c1c553591c7b7bc2ac7ee812006d9ec428a96d4ad3/gymprecice-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-04 12:46:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gymprecice",
"github_project": "gymprecice",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "gymprecice"
}
JSON
