Mid-Sized Rewrite of APIs + Devcontainer + Docs Fixes

[ludgerpaehler]

Bumps version to 0.1.3.0 in light of the changes below:

• Updates the build system from poetry to uv, in the process of which rewriting the pyproject.toml
• Adds group based dependencies to the pyproject.toml, most notably of which for rllib i.e.

pip install "hydrogym[rllib]"

installs the required additional dependencies now to run rllib with HydroGym out of the box.

• Major rewrite of the Devcontainer configuration, and the way container-packaging is done for HydroGym. The custom-built containers are fully deprecated in favor of a thin user-layer shim over the official Firedrake container, which gets pulled by the devcontainer configuration. In line with modern devcontainer convention HydroGym is not auto-installed into the environment anymore, but needs to be installed through either

pip install -e .

or

pip install ".[rllib]"

• Removes the Firedrake git submodule in favor of the modern installation approach of Firedrake, i.e. pip.
• The core abstraction has been updated to convert from the old legacy gym interface to the modern gymnasium interface. This introduces the truncation property, which we do not utilize at the current time as we are handling time limits through the reset interface, but might look to expand upon in the future.
• The rllib integration has been updated to the modern rllib interfaces, and is working seamlessly again with provided examples for a PPO training in rllib, and the tuning of a RL agent with Ray Tune.
• Firedrake imports are now wrapped in a try construct to gracefully return an error to the user in case Firedrake is not found in the current environment, but needed by HydroGym. To give an example of the construct:

try:
    import firedrake as fd
except ImportError as e:
    raise DependencyNotInstalled(
        "Firedrake is not installed, consult `https://www.firedrakeproject.org/install.html` for installation instructions."
    ) from e

• Most examples have been deprecated as they are out of date now, these will be brought back step by step, making sure that they work as intended.
• Addition of a command line interface (CLI)
• The Jupyter notebooks have been converted into a colab folder, in which they can still be launched with Jupyter, but going beyond the previous state, can be auto-launched into Google Colab using the groundwork laid by FEM-on-Colab.
• Allow for cleaner editing of default configurations by utilizing Hydra, in turn we are able to cleanly factor out default values into their own yaml configuration files, and are left with clean code without value declarations in-code.
• 2 new GitHub actions have been added, one to test-build the docs whenever they see updates, and one converting the yapf-formatting to ruff-formatting s.t. we only depend on one tool for lifting, as well as formatting now (ruff).
• Extending repository documentation
  • Fixing the Quickstart in the Readme
  • Addition of a RL framework support matrix to the Readme
• Expanding the readthedocs
  • Rewrite of the installation instructions
  • Addition of a changelog to the docs
  • Extension of the readthedocs build with the examples whose documentation is auto-built
  • New guidance on the development with the dev container
  • User documentation for running with Hydra
  • Developer documentation for running with Hydra and dialing in a test case
  • Command line interface documentation
  • Colab Usage User Documentation

[netlify]

❌ Deploy Preview for hydrogym failed.

Name	Link
🔨 Latest commit	fae58aa
🔍 Latest deploy log	https://app.netlify.com/projects/hydrogym/deploys/68429f6dc67a0600088c0dbf

[ludgerpaehler]

Presently at 677 mypy errors. To be brought down to 0 for the merge.

[netlify]

❌ Deploy Preview for hydrogym failed.

Name	Link
🔨 Latest commit	6758da6
🔍 Latest deploy log	https://app.netlify.com/projects/hydrogym/deploys/68848929005fac0008c14816

[ludgerpaehler]

Mypy to be replaced in favor of PyreFly for a better developer experience, and better IDE integration.

[ReHoss]

hi @ludgerpaehler , do you need help on this PR? Since the publication of your paper at L4DC 2025, it would indeed be nice to have the intermediate PRs (each marking an RL-controlled env which produces the RL loss curves) mentioned in #197 (comment) merged for reproducibility reasons.

@ludgerpaehler
@jcallaham
@cl126162
@nzolman

Best,

[ludgerpaehler]

Hey, just finishing off a paper today and then returning to this PR. There's a number of divergent branches, the unification of which is non-trivial so it might take a couple of days of work to get this realigned. - Ludger

[ludgerpaehler]

Deprecated. Relevant parts to be cherry-picked onto main.