{"id":19757117,"url":"https://github.com/dynamicslab/hydrogym","last_synced_at":"2025-04-05T17:03:41.700Z","repository":{"id":41273738,"uuid":"442769321","full_name":"dynamicslab/hydrogym","owner":"dynamicslab","description":"An RL-Gym for Challenge Problems in Data-Driven Modeling and Control of Fluid Dynamics.","archived":false,"fork":false,"pushed_at":"2025-03-29T11:19:08.000Z","size":103557,"stargazers_count":67,"open_issues_count":39,"forks_count":13,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-29T16:03:19.836Z","etag":null,"topics":["computational-fluid-dynamics","differentiable-physics-engine","hydrodynamics","reinforcement-learning","reinforcement-learning-environments"],"latest_commit_sha":null,"homepage":"https://hydrogym.readthedocs.io","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dynamicslab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-29T12:41:53.000Z","updated_at":"2025-03-25T22:03:54.000Z","dependencies_parsed_at":"2024-09-12T18:23:51.165Z","dependency_job_id":"056802bd-d8b1-43c0-8b3e-d1251559d68c","html_url":"https://github.com/dynamicslab/hydrogym","commit_stats":{"total_commits":229,"total_committers":7,"mean_commits":"32.714285714285715","dds":0.6157205240174672,"last_synced_commit":"dae7dd4e7151619c870f435c89bf87c774bb190c"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dynamicslab%2Fhydrogym","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dynamicslab%2Fhydrogym/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dynamicslab%2Fhydrogym/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dynamicslab%2Fhydrogym/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dynamicslab","download_url":"https://codeload.github.com/dynamicslab/hydrogym/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369953,"owners_count":20927928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computational-fluid-dynamics","differentiable-physics-engine","hydrodynamics","reinforcement-learning","reinforcement-learning-environments"],"created_at":"2024-11-12T03:18:08.652Z","updated_at":"2025-04-05T17:03:41.657Z","avatar_url":"https://github.com/dynamicslab.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003ca rel=\"nofollow\"\u003e\u003cimg alt=\"HydroGym Logo\" src=\"docs/_static/imgs/logo.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/astral-sh/ruff\"\u003e\u003cimg alt=\"Ruff\" src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\"\u003e\u003c/a\u003e\n\u003ca href=\"https://python.org/\"\u003e\u003cimg alt=\"Language: Python\" src=\"https://img.shields.io/badge/language-Python-orange.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://spdx.org/licenses/MIT.html\"\u003e\u003cimg alt=\"License WarpX\" src=\"https://img.shields.io/badge/license-MIT-blue.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://join.slack.com/t/hydrogym/shared_invite/zt-27u914dfn-UFq3CkaxiLs8dwZ_fDkBuA\"\u003e\u003cimg alt=\"Slack\" src=\"https://img.shields.io/badge/slack-hydrogym-brightgreen.svg?logo=slack\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/google/yapf\"\u003e\u003cimg alt=\"Code style: yapf\" src=\"https://img.shields.io/badge/code%20style-yapf-000000.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n\n# About this Package\n\n__IMPORTANT NOTE: This package is still ahead of an official public release, so consider anything here as an early beta. In other words, we're not guaranteeing any of this is working or correct yet. Use at your own risk__\n\nHydroGym is an open-source library of challenge problems in data-driven modeling and control of fluid dynamics.\nIt is roughly designed as an abstract interface for control of PDEs that is compatible with typical reinforcement learning APIs\n(in particular Ray/RLLib and OpenAI Gym) along with specific numerical solver implementations for some canonical flow control problems.\nCurrently these \"environments\" are all implemented using the [Firedrake](https://www.firedrakeproject.org/) finite element library.\n\n## Features\n* __Hierarchical:__ Designed for analysis and controller design **from a high-level black-box interface to low-level operator access**\n    - High-level: `hydrogym.env.FlowEnv` classes implement the OpenAI `gym.Env` interface\n    - Intermediate: Typical CFD interface with `hydrogym.FlowConfig` and `hydrogym.TransientSolver` classes\n    - Low-level: Access to linearized operators and sparse scipy or PETSc CSR matrices\n* __Modeling and analysis tools:__ Global stability analysis (via SLEPc) and modal decompositions (via modred)\n* __Scalable:__ Individual environments parallelized with MPI with a **highly scalable [Ray](https://github.com/ray-project/ray) backend reinforcement learning training**.\n\n# Installation\n\nBy design, the core components of Hydrogym are independent of the underlying solvers in order to avoid custom or complex\nthird-party library installations.\nThis means that the latest release of Hydrogym can be simply installed via [PyPI](https://pypi.org/project/hydrogym/):\n\n```bash\npip install hydrogym\n```\n\n\u003e BEWARE: The pip-package is currently behind the main repository, and we strongly urge users to build HydroGym\n\u003e         directly from the source code. Once we've stabilized the package, we will update the pip package in turn.\n\nHowever, the package assumes that the solver backend is available, so in order to run simulations locally you will\nneed to _separately_ ensure the solver backend is installed (again, currently all the environments are implemented with Firedrake).\nAlternatively (and this is important for large-scale RL training), the core Hydrogym package can (or will soon be able to) launch reinforcement learning training on a Ray-cluster without an underlying Firedrake install.\nFor more information and suggested approaches see the [Installation Docs](https://hydrogym.readthedocs.io/en/latest/installation.html).\n\nTo add HydroGym to an existing Firedrake installation, and install from the repository, run:\n\n```bash\ngit clone https://github.com/dynamicslab/hydrogym.git\ncd hydrogym\npip install .\n```\n\nAs the mesh files are stored in [git large file storage](https://git-lfs.github.com/), you will need to install git-lfs\nto download the mesh files.\n\n```bash\ngit lfs install \u0026\u0026 git lfs fetch --all\n```\n\nAt which point you are ready to run HydroGym locally.\n\n# Quickstart Guide\n\n Having installed Hydrogym into our virtual environment experimenting with Hydrogym is as easy as starting the Python interpreter\n \n ```bash\n python\n ```\n \n and then setting up a Hydrogym environment instance\n \n```python\nimport hydrogym.firedrake as hgym\nenv = hgym.FlowEnv({\"flow\": hgym.Cylinder}) # Cylinder wake flow configuration\nfor i in range(num_steps):\n    action = 0.0   # Put your control law here\n    (lift, drag), reward, done, info = env.step(action)\n```\n\nTo test that you can run individual environment instances in a multithreaded fashion, run the steady-state Newton solver on the cylinder wake with 4 processors:\n\n```bash\ncd /path/to/hydrogym/examples/cylinder\nmpiexec -np 4 python pd-control.py\n```\n\nFor more detail, check out:\n\n* A quick tour of features in `notebooks/overview.ipynb`\n* Example codes for various simulation, modeling, and control tasks in `examples`\n* The [ReadTheDocs](https://hydrogym.readthedocs.io/en/latest/)\n\n# Flow configurations\n\nThere are currently a number of main flow configurations, the most prominent of which are:\n\n- Periodic cylinder wake at Re=100\n- Chaotic pinball at Re=130\n- Open cavity at Re=7500\n- Backwards-facing step at Re=600\n\nwith visualizations of the flow configurations available in the [docs](docs/FlowConfigurations.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdynamicslab%2Fhydrogym","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdynamicslab%2Fhydrogym","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdynamicslab%2Fhydrogym/lists"}