hydrogym

A Reinforcement Learning Benchmarking Environment for Fluid Dynamics


Keywords
Reinforcement, Learning, Scientific, Machine, Benchmarking, Computational, Fluid, Dynamics, computational-fluid-dynamics, differentiable-physics-engine, hydrodynamics, reinforcement-learning, reinforcement-learning-environments
License
MIT
Install
pip install hydrogym==0.1.2.1

Documentation

About this Package

HydroGym is an open-source library of challenge problems in data-driven modeling and control of fluid dynamics.

Features

  • Hierarchical: Designed for analysis and controller design from a high-level black-box interface to low-level operator access
    • High-level: hydrogym.env.FlowEnv classes implement the OpenAI gym.Env interface
    • Intermediate: Typical CFD interface with hydrogym.FlowConfig and hydrogym.TransientSolver classes
    • Low-level: Access to linearized operators and sparse scipy or PETSc CSR matrices
  • Modeling and anlysis tools: Global stability analysis (via SLEPc) and modal decompositions (via modred)
  • Scalable: Individual environments parallelized with MPI with a highly scalable Ray backend reinforcement learning training.

Installation

To begin using Hydrogym we can install its latest release via PyPI with pip

pip install hydrogym

which provides the core functionality, and is able to launch reinforcement learning training on a Ray-cluster without an underlying Firedrake install. If you want to play around with Hydrogym locally on e.g. your laptop, we recommend a local Firedrake install. The instructions for which can be found in the Installation Docs.

Quickstart Guide

Having installed Hydrogym into our virtual environment experimenting with Hydrogym is as easy as starting the Python interpreter

python

and then setting up a Hydrogym environment instance

import hydrogym as hgym
env = hgym.env.CylEnv(Re=100) # Cylinder wake flow configuration
for i in range(num_steps):
    action = 0.0   # Put your control law here
    (lift, drag), reward, done, info = env.step(action)

To 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:

cd /path/to/hydrogym/examples/cylinder
mpiexec -np 4 python pd-control.py

For more detail, check out:

  • A quick tour of features in notebooks/overview.ipynb
  • Example codes for various simulation, modeling, and control tasks in examples
  • The ReadTheDocs

Flow configurations

There are currently a number of main flow configurations, the most prominent of which are:

  • Periodic cyclinder wake at Re=100
  • Chaotic pinball at Re=130
  • Open cavity at Re=7500

with visualizations of the flow configurations available in the docs.