gymprecice / gymprecice Goto Github PK

Gym-preCICE is a Python preCICE adapter fully compliant with Gymnasium (also known as OpenAI Gym) 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.

Gymnasium: Installed by default. Refer to the Gymnasium for more information.

preCICE: You need to install the preCICE library. Refer to the preCICE documentation for information on building and installation (tested on preCICE release v2.5.0).

preCICE Python bindings: Installed by default. Refer to the python language bindings for preCICE for information.

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:

• create and activate a conda virtual environment:

 conda create -n gymprecice python=3.8
 conda activate gymprecice

• install the adapter:

python3 -m pip install gymprecice

• run a simple test to check gymprecice installation (this should pass silently without any error/warning messages):

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.

• if you are contributing a pull request, it is best to install from the source:

git clone https://github.com/gymprecice/gymprecice.git
cd gymprecice
pip install -e .
pip install -e .[dev]
pre-commit install

We use pytest framework to run unit tests for all modules in our package. You need to install required dependencies before running any test:

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

Please refer to tutorials for the details on how to use the adapter. You can check out the Quickstart in our tutorials repository to try a ready-to-run control case. You need to install some of the required dependencies before running any tutorial:

python3 -m pip install gymprecice[tutorial]

If you use Gym-preCICE, please cite the following paper:

@misc{shams2023gymprecice,
      title = {Gym-preCICE: Reinforcement learning environments for active flow control},
      author = {Shams, Mosayeb and Elsheikh, Ahmed H},
      journal = {SoftwareX},
      volume = {23},
      pages = {101446},
      year = {2023},
      issn = {2352-7110},
      doi = {https://doi.org/10.1016/j.softx.2023.101446},
      eprint = {https://arxiv.org/abs/2305.02033},
}

See the contributing guidelines CONTRIBUTING.md for information on submitting issues and pull requests.

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) - Co-developer and Supervisor (Heriot-Watt University)

This work was supported by the Engineering and Physical Sciences Research Council grants number EP/V048899/1 and EP/Y006143/1.

Gym-preCICE and its tutorials are MIT licensed.