HydroBayesCal

Surrogate-assisted Bayesian calibration for computationally expensive hydro- and morphodynamic models.

HydroBayesCal calibrates expensive numerical models without running them thousands of times. It trains a Gaussian Process Emulator (GPE) as a fast surrogate from a small set of strategically sampled simulations, then refines it with Bayesian Active Learning (BAL), iteratively adding the training points that maximise the information gain (relative entropy) and Bayesian model evidence for the calibration. Single- and multi-output GPEs are supported.

The package couples to open-source modelling software through a common binding layer:

• TELEMAC (2D/3D) is fully supported, including multi-discharge calibration (one shared parameter set against several steady flows at once; see the docs "Multi-discharge calibration with TELEMAC")
• OpenFOAM (interFoam) bindings are under active development

Experimental design and parameter sampling are delegated to BayesValidRox; the GP emulators and the Bayesian active-learning logic are implemented in-tree.

Installation

HydroBayesCal requires Python ≥ 3.10 (tested on 3.10-3.12). It is developed and tested on Linux.

pip install hydroBayesCal

or, for a development/editable install from a clone:

git clone https://github.com/Ecohydraulics/hydrobayescal.git
cd hydrobayescal
pip install -e ".[dev,docs,mesh]"

A calibration additionally requires a working installation of the numerical solver (e.g. TELEMAC) on the system. See the installation guide for the full environment setup, including coupling HydroBayesCal with TELEMAC.

Quick start

Configure a calibration in a Python config file and run the TELEMAC driver:

python templates/bal_telemac.py --config templates/config_Telemac.py

Simulation results can also be sampled at arbitrary points outside the calibration workflow, including depth-explicit extraction from TELEMAC-3D and OpenFOAM output:

import hydroBayesCal as hbc

df = hbc.extract_results("r3d_steady.slf", variable="velocity",
                         x=[371522.5, 371540.0], y=[5345152.0, 5345170.0],
                         z=0.05)  # height above the local bed

See the documentation for the end-to-end workflow, the configuration parameters, the code architecture, and worked examples.

Development & releases

Contributions are welcome, see CONTRIBUTING.md for the development setup, coding conventions, and the documentation build.

For maintainers, a few essentials:

• Editable install: pip install -e ".[dev,docs,mesh]" (Python >= 3.10, tested 3.10-3.12).
• Versioning: Semantic Versioning / PEP 440; the version lives only in pyproject.toml (keep docs/conf.py in sync). PyPI versions are immutable, so always bump for a new release.
• Releases are automated: publishing a GitHub Release (tag vX.Y.Z) triggers .github/workflows/publish.yml, which builds the distributions and uploads them to PyPI via Trusted Publishing (OIDC, no stored token). No manual twine upload is needed. Build locally to sanity-check with python -m build && twine check dist/*.

Citing / scientific background

HydroBayesCal builds on the Bayesian active-learning framework of Oladyshkin et al. (2020) and on Gaussian-process regression (Rasmussen & Williams, 2006). Its application to reservoir sedimentation and 3D reservoir hydrodynamics is documented in Mouris et al. (2023) and Schwindt et al. (2023). Full references with DOIs are on the references page.

License

Distributed under the BSD 3-Clause License. See LICENSE.