[][relexi_github]
[](LICENSE.md)
[](https://doi.org/10.1016/j.simpa.2022.100422)
[][relexi_docs]
[](https://pypi.org/project/relexi/)
[][relexi_github]
# About Relexi
Relexi is a Reinforcement Learning (RL) framework developed for the high-order HPC flow solver [FLEXI][flexi].
However, Relexi is developed with modularity in mind and allows to used with other HPC solvers as well.
Relexi builds upon TensorFlow and its RL extension TF-Agents.
For the efficient communication, data handling and the managment of the simulations runs on HPC systems, Relexi uses the SmartSim package with its SmartRedis communication clients.
For details on its scaling behavior, suitability for HPC and for use cases, please see
* [Kurz, M., Offenhäuser, P., Viola, D., Resch, M., & Beck, A. (2022). Relexi—A scalable open source reinforcement learning framework for high-performance computing. Software Impacts, 14, 100422.](https://doi.org/10.1016/j.simpa.2022.100422)
* [Kurz, M., Offenhäuser, P., Viola, D., Shcherbakov, O., Resch, M., & Beck, A. (2022). Deep Reinforcement Learning for Computational Fluid Dynamics on HPC Systems. Journal of Computational Science, 65, 101884.](https://doi.org/10.1016/j.jocs.2022.101884)
* [Kurz, M., Offenhäuser, P., & Beck, A. (2023). Deep reinforcement learning for turbulence modeling in large eddy simulations. International Journal of Heat and Fluid Flow, 99, 109094.](https://doi.org/10.1016/j.ijheatfluidflow.2022.109094)
* [Beck, A., & Kurz, M. (2023). Toward discretization-consistent closure schemes for large eddy simulation using reinforcement learning. Physics of Fluids, 35(12), 125122.](https://doi.org/10.1063/5.0176223)
This is a scientific project.
If you use Relexi or find it helpful, please cite the project using a suitable reference from the list above referring to either the general Relexi project, its HPC aspects or its application for scientific modeling tasks, respectively.
# Installation
The following quick start guide covers a standard installation of the Relexi framework.
### Dependencies
Relexi has a variety of dependencies.
The main dependencies of Relexi are listed in the following with their supported version.
| Package | Version | Note |
|:-----------------|----------------:|:----------------------------------------|
| Python | ≥3.9 | |
| CMake | ≥3.0 | |
| Make | ≥4.0 | |
| gcc-fortran | ≥9.4 | gcc 10 not supported! (gcc ≥11 is fine) |
| gcc | ≥9.4 | |
| gcc-c++ | ≥9.4 | |
Be aware that the major dependencies (SmartSim, TensorFlow, FLEXI) might have a more expansive dependency tree, for which we refer the user to the corresponding documentations for details.
### Prerequisites
Open a terminal and change into the directory where you want to install Relexi and its dependecies.
It is highly recommended to use some form of virtual environment for the installation.
You can use create and activate a new environment using `virtualenv` via
```bash
pip install virtualenv
virtualenv env_relexi
source env_relexi/bin/activate
```
### Install Relexi
Relexi can be installed most simply with `pip` via
```bash
pip install relexi
```
Alternatively, it can be installed as editable package from the repository with
```bash
git clone https://github.com/flexi-framework/relexi.git
pip install -e relexi/
```
### Build SmartSim
After installing the `smartsim` package via pip, its database backend has to be installed with its dependencies via the `smart` commandline tool:
```bash
smart clobber && smart clean
smart build --no_pt
```
### Install FLEXI
Clone the required version of FLEXI from GitHub and build it with the standard compile flags
```bash
git clone --branch smartsim --depth 1 https://github.com/flexi-framework/flexi-extensions.git
cd flexi-extensions
mkdir -p build && cd build
cmake .. -DLIBS_BUILD_HDF5=ON -DLIBS_USE_MPI=OFF -DLIBS_BUILD_SMARTREDIS=ON -DLIBS_USE_SMARTREDIS=ON -DLIBS_USE_FFTW=ON -DPOSTI=OFF -DFLEXI_TESTCASE=hit -DFLEXI_NODETYPE=GAUSS-LOBATTO -DFLEXI_SPLIT_DG=ON -DFLEXI_EDDYVISCOSITY=ON
make -j
cd ../../
```
Note that in this configuration FLEXI tries to install all its dependencies automatically, which can require several minutes.
If HDF5 is available on the system, the compile time can be reduced significantly by switching off the corresponding flag in the CMake configuration.
Moreover, this configuration compiles FLEXI without MPI and thus in its serial version.
To enable MPI or to change the configuration of FLEXI, please see its [official documentation][userguide] for more details.
# Running the Code
Relexi comes with some example setups to verify that it is correctly installed.
Enter the directory of the first test case and run Relexi using its CLI.
```bash
cd relexi/examples/HIT_24_DOF/
relexi prm.yaml
```
The file ``prm.yaml`` contains the configuration for the reinforcement learning training.
It can be adapted using the text editor of your choice.
If you have installed the ``flexi`` binary not in the default path, adapt the path of the executable under ``executabl_path`` accordingly.
You may also set the number of parallel environments by setting ``num_parallel_environments`` according to your local hardware resources.
The number of processors used for each FLEXI environment can also be changed by setting ``num_procs_per_environment`` to the appropriate value.
Be aware that for using FLEXI in parallel, i.e. with more than 1 CPU core per environment, it has to be compiled with MPI.
Please refer to the [FLEXI documentation][userguide] for details.
# Results
To visualize the results, Relexi uses the TensorBoard suite.
After running the code, Relexi should create a directory ``logs``, where the model, training checkpoints and the training metrics are saved.
Open it with
```bash
tensorboard --logdir logs/
```
Tensorboard then provides a URL that can be opened in the Browser.
If the training is performed on a remote server, the port where TensorBoard sends its data has to be redirected to your local machine. If you use `ssh` to connect to the server, you can redirect the standard TensorBoard port (6006) with
```bash
ssh -L 6006:127.0.0.1:6006 your_remote_server
```
# Documentation
The documentation of Relexi can be found [here][relexi_docs].
It is built with the [`pdoc`](https://github.com/mitmproxy/pdoc) package, which is included in the [`requirements.txt`](requirements.txt) and thus is already installed with Relexi.
To build the documentation yourself, execute
```bash
cd docs
bash build_docs.sh
```
Open the resulting `index.html` with your browser.
# Testing
A suite of unit tests is implemented for Relexi using the [`pytest`](https://docs.pytest.org/) testing environment. To run the tests, simply execute in the root directory
```bash
pytest
```
[nrg]: https://numericsresearchgroup.org/index.html
[flexi]: https://numericsresearchgroup.org/flexi_index.html
[userguide]: https://numericsresearchgroup.org/userguide/userguide.pdf
[relexi_docs]: https://flexi-framework.github.io/relexi/relexi.html
[relexi_github]: https://github.com/flexi-framework/relexi
Raw data
{
"_id": null,
"home_page": "https://flexi-framework.github.io/relexi/",
"name": "relexi",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "reinforcement learning, machine learning, high-performance computing, simulation",
"author": "Marius Kurz",
"author_email": "marius.kurz@cwi.nl",
"download_url": "https://files.pythonhosted.org/packages/f4/75/ca42bf14dfae03b2f5daf5d29822a7f3f50119d4b2de584d4a462dc03a39/relexi-2.0.0.tar.gz",
"platform": null,
"description": "[![logo](https://numericsresearchgroup.org/images/icons/relexi.svg \"RELEXI\")][relexi_github]\n\n[![license](https://img.shields.io/github/license/flexi-framework/relexi.svg?maxAge=2592000 \"GPL-3.0 License\")](LICENSE.md)\n[![doi](https://img.shields.io/badge/DOI-10.1016/j.simpa.2022.100422-blue \"DOI\")](https://doi.org/10.1016/j.simpa.2022.100422)\n[![docsbuild](https://github.com/flexi-framework/relexi/actions/workflows/docs.yml/badge.svg \"Documentation\")][relexi_docs]\n[![pypi](https://img.shields.io/pypi/v/relexi \"PyPI\")](https://pypi.org/project/relexi/)\n[![github](https://img.shields.io/badge/View%20on%20GitHub-%23121011.svg?logo=github&logoColor=white \"GitHub\")][relexi_github]\n\n# About Relexi\nRelexi is a Reinforcement Learning (RL) framework developed for the high-order HPC flow solver [FLEXI][flexi].\nHowever, Relexi is developed with modularity in mind and allows to used with other HPC solvers as well.\nRelexi builds upon TensorFlow and its RL extension TF-Agents.\nFor the efficient communication, data handling and the managment of the simulations runs on HPC systems, Relexi uses the SmartSim package with its SmartRedis communication clients.\nFor details on its scaling behavior, suitability for HPC and for use cases, please see\n* [Kurz, M., Offenh\u00e4user, P., Viola, D., Resch, M., & Beck, A. (2022). Relexi\u2014A scalable open source reinforcement learning framework for high-performance computing. Software Impacts, 14, 100422.](https://doi.org/10.1016/j.simpa.2022.100422)\n* [Kurz, M., Offenh\u00e4user, P., Viola, D., Shcherbakov, O., Resch, M., & Beck, A. (2022). Deep Reinforcement Learning for Computational Fluid Dynamics on HPC Systems. Journal of Computational Science, 65, 101884.](https://doi.org/10.1016/j.jocs.2022.101884)\n* [Kurz, M., Offenh\u00e4user, P., & Beck, A. (2023). Deep reinforcement learning for turbulence modeling in large eddy simulations. International Journal of Heat and Fluid Flow, 99, 109094.](https://doi.org/10.1016/j.ijheatfluidflow.2022.109094)\n* [Beck, A., & Kurz, M. (2023). Toward discretization-consistent closure schemes for large eddy simulation using reinforcement learning. Physics of Fluids, 35(12), 125122.](https://doi.org/10.1063/5.0176223)\n\nThis is a scientific project.\nIf you use Relexi or find it helpful, please cite the project using a suitable reference from the list above referring to either the general Relexi project, its HPC aspects or its application for scientific modeling tasks, respectively.\n\n# Installation\nThe following quick start guide covers a standard installation of the Relexi framework.\n\n### Dependencies\nRelexi has a variety of dependencies.\nThe main dependencies of Relexi are listed in the following with their supported version.\n\n| Package | Version | Note |\n|:-----------------|----------------:|:----------------------------------------|\n| Python | \u22653.9 | |\n| CMake | \u22653.0 | |\n| Make | \u22654.0 | |\n| gcc-fortran | \u22659.4 | gcc 10 not supported! (gcc \u226511 is fine) |\n| gcc | \u22659.4 | |\n| gcc-c++ | \u22659.4 | |\n\nBe aware that the major dependencies (SmartSim, TensorFlow, FLEXI) might have a more expansive dependency tree, for which we refer the user to the corresponding documentations for details.\n\n### Prerequisites\nOpen a terminal and change into the directory where you want to install Relexi and its dependecies.\nIt is highly recommended to use some form of virtual environment for the installation.\nYou can use create and activate a new environment using `virtualenv` via\n```bash\npip install virtualenv\nvirtualenv env_relexi\nsource env_relexi/bin/activate\n```\n\n### Install Relexi\nRelexi can be installed most simply with `pip` via\n```bash\npip install relexi\n```\n\nAlternatively, it can be installed as editable package from the repository with\n```bash\ngit clone https://github.com/flexi-framework/relexi.git\npip install -e relexi/\n```\n\n### Build SmartSim\nAfter installing the `smartsim` package via pip, its database backend has to be installed with its dependencies via the `smart` commandline tool:\n```bash\nsmart clobber && smart clean\nsmart build --no_pt\n```\n\n### Install FLEXI\nClone the required version of FLEXI from GitHub and build it with the standard compile flags\n```bash\ngit clone --branch smartsim --depth 1 https://github.com/flexi-framework/flexi-extensions.git\ncd flexi-extensions\nmkdir -p build && cd build\ncmake .. -DLIBS_BUILD_HDF5=ON -DLIBS_USE_MPI=OFF -DLIBS_BUILD_SMARTREDIS=ON -DLIBS_USE_SMARTREDIS=ON -DLIBS_USE_FFTW=ON -DPOSTI=OFF -DFLEXI_TESTCASE=hit -DFLEXI_NODETYPE=GAUSS-LOBATTO -DFLEXI_SPLIT_DG=ON -DFLEXI_EDDYVISCOSITY=ON\nmake -j\ncd ../../\n```\nNote that in this configuration FLEXI tries to install all its dependencies automatically, which can require several minutes.\nIf HDF5 is available on the system, the compile time can be reduced significantly by switching off the corresponding flag in the CMake configuration.\nMoreover, this configuration compiles FLEXI without MPI and thus in its serial version.\nTo enable MPI or to change the configuration of FLEXI, please see its [official documentation][userguide] for more details.\n\n# Running the Code\nRelexi comes with some example setups to verify that it is correctly installed.\nEnter the directory of the first test case and run Relexi using its CLI.\n```bash\ncd relexi/examples/HIT_24_DOF/\nrelexi prm.yaml\n```\nThe file ``prm.yaml`` contains the configuration for the reinforcement learning training.\nIt can be adapted using the text editor of your choice.\nIf you have installed the ``flexi`` binary not in the default path, adapt the path of the executable under ``executabl_path`` accordingly.\nYou may also set the number of parallel environments by setting ``num_parallel_environments`` according to your local hardware resources.\nThe number of processors used for each FLEXI environment can also be changed by setting ``num_procs_per_environment`` to the appropriate value.\nBe aware that for using FLEXI in parallel, i.e. with more than 1 CPU core per environment, it has to be compiled with MPI.\nPlease refer to the [FLEXI documentation][userguide] for details.\n\n# Results\nTo visualize the results, Relexi uses the TensorBoard suite.\nAfter running the code, Relexi should create a directory ``logs``, where the model, training checkpoints and the training metrics are saved.\nOpen it with\n```bash\ntensorboard --logdir logs/\n```\nTensorboard then provides a URL that can be opened in the Browser.\nIf the training is performed on a remote server, the port where TensorBoard sends its data has to be redirected to your local machine. If you use `ssh` to connect to the server, you can redirect the standard TensorBoard port (6006) with\n```bash\nssh -L 6006:127.0.0.1:6006 your_remote_server\n```\n\n# Documentation\nThe documentation of Relexi can be found [here][relexi_docs].\nIt is built with the [`pdoc`](https://github.com/mitmproxy/pdoc) package, which is included in the [`requirements.txt`](requirements.txt) and thus is already installed with Relexi.\nTo build the documentation yourself, execute\n```bash\ncd docs\nbash build_docs.sh\n```\nOpen the resulting `index.html` with your browser.\n\n# Testing\nA suite of unit tests is implemented for Relexi using the [`pytest`](https://docs.pytest.org/) testing environment. To run the tests, simply execute in the root directory\n```bash\npytest\n```\n\n[nrg]: https://numericsresearchgroup.org/index.html\n[flexi]: https://numericsresearchgroup.org/flexi_index.html\n[userguide]: https://numericsresearchgroup.org/userguide/userguide.pdf\n[relexi_docs]: https://flexi-framework.github.io/relexi/relexi.html\n[relexi_github]: https://github.com/flexi-framework/relexi\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "A reinforcement learning library for simulation environments on high-performance computing systems.",
"version": "2.0.0",
"project_urls": {
"Documentation": "https://flexi-framework.github.io/relexi/",
"Homepage": "https://flexi-framework.github.io/relexi/",
"Repository": "https://github.com/flexi-framework/relexi/"
},
"split_keywords": [
"reinforcement learning",
" machine learning",
" high-performance computing",
" simulation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d5527c66b914870edecb6852dc4924314837b9a6efad7fc3f442b62f491098c5",
"md5": "3ffe7d0a294912ebb27aa86a5db987e1",
"sha256": "a05fec6625760c6a46e9c85f08324bf29565738dbfce7ddb9bcefe0da824ffe2"
},
"downloads": -1,
"filename": "relexi-2.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "3ffe7d0a294912ebb27aa86a5db987e1",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 54260,
"upload_time": "2024-07-26T21:56:23",
"upload_time_iso_8601": "2024-07-26T21:56:23.610955Z",
"url": "https://files.pythonhosted.org/packages/d5/52/7c66b914870edecb6852dc4924314837b9a6efad7fc3f442b62f491098c5/relexi-2.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f475ca42bf14dfae03b2f5daf5d29822a7f3f50119d4b2de584d4a462dc03a39",
"md5": "bdd791b98a004ad88a9c6dca6acef311",
"sha256": "fe3423d12f7f63d9d01653450cdf653c501f93fc7601f5f82034cce349508098"
},
"downloads": -1,
"filename": "relexi-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "bdd791b98a004ad88a9c6dca6acef311",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 43386,
"upload_time": "2024-07-26T21:56:25",
"upload_time_iso_8601": "2024-07-26T21:56:25.801468Z",
"url": "https://files.pythonhosted.org/packages/f4/75/ca42bf14dfae03b2f5daf5d29822a7f3f50119d4b2de584d4a462dc03a39/relexi-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-26 21:56:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "flexi-framework",
"github_project": "relexi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "relexi"
}
JSON
