Skip to content

Clarify Hub case-data inventory semantics #310

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
LittleLeaf1018 wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Clarify Hub case-data inventory semantics #310

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d14df3f
Clarify Hub case-data inventory semantics
Oct 14, 2026
717dcb7
docs: scope Hub loaders to backend APIs
Oct 14, 2026
9334fd2
docs: clarify backend integration scope
Oct 14, 2026
27d1825
docs: align backend integration headline
Oct 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 15 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,19 +11,19 @@

# HydroGym: Reinforcement Learning for Fluid Dynamics

**61+ environments | 6 solver backends | 2D & 3D | Ready for RL training**
**Six backend integrations | 2D & 3D | Gymnasium-compatible interface**

HydroGym is a comprehensive platform for applying reinforcement learning to fluid dynamics and flow control. With environments ranging from canonical benchmarks to turbulent flows, HydroGym provides a standardized Gymnasium-compatible interface for training RL agents on challenging CFD problems.

## Key Features

- **Diverse Environments**: 61+ pre-configured environments across 6 CFD solvers
- **Hub Case Data**: Pre-configured solver case data is published in the HydroGym Hugging Face dataset
- **Standard RL Interface**: Gymnasium-compatible API works with Stable-Baselines3, RLlib, and other RL libraries
- **Compute Efficient**: Highly optimized GPU & CPU backends for efficient RL deployment ranging from local workstations to exascale HPC systems
- **Scalable**: MPI-parallelized solvers with distributed RL training support
- **Multiple Backends**: Finite Element (Firedrake), Lattice Boltzmann (MAIA LBM), Finite Volume (MAIA FV), Spectral Element (NEK5000), Fully Differentiable solvers (JAX-Fluids)
- **Multiple Backends**: Finite Element (Firedrake), Lattice Boltzmann (MAIA), Finite Volume (MAIA FV and JAX-Fluids), Spectral Element (NEK5000), and differentiable solvers (JAX)
- **2D & 3D**: From simple 2D benchmarks to complex 3D turbulent flows (Re up to 400,000)
- **Research-Ready**: Managed by a complementary HuggingFace repository
- **Named Case Data**: Some backend APIs retrieve case data from the Hub by case-data ID; supported loaders vary by backend

## Quick Start with Docker (Recommended)

Expand All @@ -41,18 +41,18 @@ docker pull clagemann/hydrogym-rocm-6.3.3:latest
# Run container
docker run -it --gpus all clagemann/hydrogym-nvhpc-26.1_cuda-12.9_turing_ampere:latest
```
## Available Environments
## Solver Backends and Hub Case Data

HydroGym provides **61 environments** across 6 solver backends:
At dataset revision [`cf5ef6748443ae72e9647f398487e98d421a7243`](https://huggingface.co/datasets/dynamicslab/HydroGym-environments/tree/cf5ef6748443ae72e9647f398487e98d421a7243), the Hub contains 89 top-level case-data directories. This is a file inventory, not a count of independently instantiable or runtime-validated environments. HydroGym's runtime environment listing follows the Hub's default branch when no dataset revision is specified, so the inventory can change.

| Solver Backend | Count | Description | Dimensions |
|----------------|-------|-------------|------------|
| **Firedrake** (FEM) | 20 | Canonical flow control benchmarks | 2D |
| **MAIA LBM** | 55 | Lattice Boltzmann method environments | 2D, 3D |
| **MAIA Structured FV** | 8 | High-Reynolds turbulent boundary layers | 3D |
| **NEK5000** | 2 | Spectral element turbulent channel flow | 3D |
| **JAX** | 2 | Differentiable fluid dynamics | 2D, 3D |
| **JAX-Fluids** | 2 | Compressible shock vector control | 2D, 3D |
| Solver Backend | Method | Description | Dimensions |
|----------------|--------|-------------|------------|
| **Firedrake** | FEM | Canonical flow control benchmarks | 2D |
| **MAIA LBM** | Lattice Boltzmann | Flow control benchmarks | 2D, 3D |
| **MAIA Structured FV** | Finite volume | High-Reynolds turbulent boundary layers | 3D |
| **NEK5000** | Spectral element | Turbulent channel flow | 3D |
| **JAX** | Differentiable solvers | Fluid dynamics | 2D, 3D |
| **JAX-Fluids** | Differentiable finite volume | Compressible flow control | 2D, 3D |

### Environment Categories

Expand Down Expand Up @@ -83,7 +83,7 @@ HydroGym provides **61 environments** across 6 solver backends:

## Environment Checkpoints

All required environment checkpoints are available via [HuggingFace](https://huggingface.co/datasets/dynamicslab/HydroGym-environments/tree/main) and are downloaded on the fly when an environment is first created (internet connection required). If no internet connection is available at runtime — e.g. on compute nodes in HPC clusters — you can pre-download the environment files as outlined in [examples/maia/README.md](examples/maia/README.md).
Pre-configured case data is published through [Hugging Face](https://huggingface.co/datasets/dynamicslab/HydroGym-environments). Whether files are downloaded during environment setup, and how to stage them for offline use, depends on the selected backend. Follow its backend guide; MAIA offline usage is described in [examples/maia/README.md](examples/maia/README.md).

## Examples

Expand Down
2 changes: 1 addition & 1 deletion docs/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

This is the **documentation site** for HydroGym, a reinforcement learning platform for fluid dynamics. The docs are built with Docusaurus and live in the `/docs` subdirectory of the main HydroGym repository.

HydroGym provides 88 RL environments across 6 CFD solver backends (Firedrake, MAIA LBM, MAIA FV, NEK5000, JAX, JAX-Fluids) for training agents on flow control problems.
HydroGym integrates six CFD solver backends (Firedrake, MAIA LBM, MAIA FV, NEK5000, JAX, JAX-Fluids) and a Hugging Face dataset of named solver case data. Hub directory counts are data inventory only; do not present them as counts of runtime-validated environments or backend coverage.

## Common Commands

Expand Down
24 changes: 12 additions & 12 deletions docs/docs/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,22 @@ sidebar_position: 1

![HydroGym overview — six solver backends, environments ranging from 2-D cylinder wakes to 3-D turbulent boundary layers](/img/HydroGymOverview.png)

HydroGym is a reinforcement learning platform for active flow control in fluid dynamics. It provides a unified, [Gymnasium](https://gymnasium.farama.org/)-compatible interface to 88 pre-configured CFD environments that span six solver backends, two to three spatial dimensions, and Reynolds numbers from laminar benchmarks to wall-bounded turbulence above Re = 400 000.
HydroGym is a reinforcement learning platform for active flow control in fluid dynamics. It provides a unified, [Gymnasium](https://gymnasium.farama.org/)-compatible interface across six solver backends. The Hugging Face dataset publishes named solver case data; its directory count is an input-data inventory, not a count of runtime-validated environments or backend coverage.

The central design goal is to make it straightforward to apply standard RL tooling and techniques — [Stable-Baselines3](https://stable-baselines3.readthedocs.io/), [TorchRL](https://github.com/pytorch/rl), [RLlib](https://docs.ray.io/en/latest/rllib/index.html), [PettingZoo](https://pettingzoo.farama.org/), or your own training loop — to a broad set of physically meaningful flow control problems without having to write a custom environment or solver interface. Every environment exposes the same `env.reset()` / `env.step()` API; solver-specific setup is handled behind the scenes.
The central design goal is to make it straightforward to apply standard RL tooling and techniques — [Stable-Baselines3](https://stable-baselines3.readthedocs.io/), [TorchRL](https://github.com/pytorch/rl), [RLlib](https://docs.ray.io/en/latest/rllib/index.html), [PettingZoo](https://pettingzoo.farama.org/), or your own training loop — to flow control problems without having to write a custom interface. Successfully instantiated environments expose the Gymnasium `env.reset()` / `env.step()` API; solver setup and optional runtime requirements remain backend-specific.

Environment configurations and initial-condition checkpoints are distributed through [HuggingFace Hub](https://huggingface.co/datasets/dynamicslab/HydroGym-environments) as a dedicated dataset and are downloaded automatically the first time an environment is created. Pre-built Docker images are available for all solver backends, making it possible to go from zero to a running training loop in a single `docker pull` command.
Pre-configured case data is distributed through [Hugging Face Hub](https://huggingface.co/datasets/dynamicslab/HydroGym-environments). A directory being present in the dataset does not by itself establish that it instantiates with a particular backend version. Pre-built Docker images are available for solver backends; follow the backend-specific installation and verification instructions before training.

The six presently supported solver backends are:
The six backend integrations are:

| Backend | Method | Environments | Dimensions |
|---------|--------|:---:|---|
| [Firedrake](./installation/firedrake) | Finite element (FEM) | 20 | 2-D |
| [MAIA LBM](./installation/maia) | Lattice Boltzmann | 55 | 2-D, 3-D |
| [MAIA Structured FV](./installation/maia) | Finite volume | 8 | 3-D |
| [NEK5000](./installation/nek5000) | Spectral element (SEM) | 1 | 3-D |
| [JAX](./installation/jax) | Spectral / finite-difference, fully differentiable | 2 | 2-D, 3-D |
| [JAX-Fluids](./installation/jaxfluids) | Compressible finite volume, fully differentiable | 2 | 2-D, 3-D |
| Backend | Method | Dimensions |
|---------|--------|---|
| [Firedrake](./installation/firedrake) | Finite element (FEM) | 2-D |
| [MAIA LBM](./installation/maia) | Lattice Boltzmann | 2-D, 3-D |
| [MAIA Structured FV](./installation/maia) | Finite volume | 3-D |
| [NEK5000](./installation/nek5000) | Spectral element (SEM) | 3-D |
| [JAX](./installation/jax) | Spectral / finite-difference, fully differentiable | 2-D, 3-D |
| [JAX-Fluids](./installation/jaxfluids) | Compressible finite volume, fully differentiable | 2-D, 3-D |

To get a solver running immediately, proceed to the [Quickstart](./quickstart).

22 changes: 11 additions & 11 deletions docs/docs/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,26 +58,26 @@ You should now be able to connect from your local ParaView client — the local

## Run environments

HydroGym provides **88 environments** across 6 solver backends:
The Hugging Face dataset stores named directories of pre-configured solver case data. A directory listing is an input-data inventory; it does not establish that every case can be instantiated with every optional backend or solver version. Use the matching backend guide and run a case-specific smoke test before training.

| Solver backend | Count | Description | Dimensions |
| --- | ---: | --- | --- |
| **Firedrake** `FEM` | 20 | Canonical flow control benchmarks | 2D |
| **MAIA** `LBM` | 55 | Lattice Boltzmann method environments | 2D, 3D |
| **MAIA** `STRUCTURED FV` | 8 | High-Reynolds turbulent boundary layers | 3D |
| **NEK5000** `SEM` | 1 | Spectral element turbulent channel flow | 3D |
| **JAX** `SEM, FD` | 2 | Differentiable fluid dynamics | 2D, 3D |
| **JAX-Fluids** `FVM` | 2 | Compressible jet engine control | 2D, 3D |
| Solver backend | Method | Description | Dimensions |
| --- | --- | --- | --- |
| **Firedrake** | FEM | Canonical flow control benchmarks | 2D |
| **MAIA** | Lattice Boltzmann | Flow control cases | 2D, 3D |
| **MAIA** | Structured finite volume | High-Reynolds turbulent boundary layers | 3D |
| **NEK5000** | Spectral element | Turbulent channel flow | 3D |
| **JAX** | Spectral / finite difference | Differentiable fluid dynamics | 2D, 3D |
| **JAX-Fluids** | Finite volume | Compressible flow control | 2D, 3D |

HydroGym interfaces with [Hugging Face](https://huggingface.co/datasets/dynamicslab/HydroGym-environments) to easily set up fluid environments. Hugging Face currently contains several pre-configured environments that can be loaded via `.from_hf()`. For instance, MAIA environments can be loaded as follows:
HydroGym publishes named case data on [Hugging Face](https://huggingface.co/datasets/dynamicslab/HydroGym-environments), but loader APIs vary by backend. MAIA exposes `maia.from_hf(...)`; NEK exposes `NekEnv.from_hf(...)` with a required `nproc` argument. See the [MAIA](installation/maia) and [NEK5000](installation/nek5000) guides for their loading paths and prerequisites. For example, MAIA case data can be requested as follows:

```python
import hydrogym.maia as maia

env = maia.from_hf("Cylinder_2D_Re200")
```

Several pre-configured environments are available to load from Hugging Face. A list of environments and their exact naming conventions can be found [in this breakdown](https://github.com/dynamicslab/hydrogym/blob/main/existing_environments.yaml). For further detail on customizing environments and running RL scripts, jump to the [RL training](#rl-training) section.
The Hub’s top-level directory names are case-data IDs, not evidence that each directory has been instantiated or validated with the current solver stack. See the [dataset](https://huggingface.co/datasets/dynamicslab/HydroGym-environments) for current IDs and naming conventions. For further detail on customizing cases and running RL scripts, jump to the [RL training](#rl-training) section.

### MAIA

Expand Down