Metadata-Version: 2.4
Name: hydroBayesCal
Version: 0.1.1
Summary: Surrogate-assisted Bayesian calibration for hydrodynamic and morphodynamic models (Telemac, OpenFOAM).
Author: Sebastian Schwindt, Andres Heredia, Eduardo Acuna
License-Expression: BSD-3-Clause
Project-URL: Documentation, https://hydrobayescal.readthedocs.io
Project-URL: Source, https://github.com/sschwindt/hydrobayescal
Keywords: Bayesian calibration,Gaussian process emulator,surrogate model,Bayesian active learning,Telemac,OpenFOAM
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: pandas>=2.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: h5py>=3.10
Requires-Dist: openpyxl>=3.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: matplotlib>=3.7
Requires-Dist: seaborn>=0.13
Requires-Dist: corner>=2.2
Requires-Dist: tqdm>=4.66
Requires-Dist: rich>=13
Requires-Dist: joblib>=1.3
Requires-Dist: pyvista>=0.43
Requires-Dist: torch>=2.2
Requires-Dist: gpytorch>=1.11
Requires-Dist: linear-operator>=0.5
Requires-Dist: emcee>=3.1
Requires-Dist: chaospy>=4.3
Requires-Dist: bayesvalidrox>=2.1
Provides-Extra: mesh
Requires-Dist: vtk>=9.2; extra == "mesh"
Requires-Dist: meshio>=5.3; extra == "mesh"
Requires-Dist: rasterio>=1.3; extra == "mesh"
Requires-Dist: affine>=2.4; extra == "mesh"
Provides-Extra: server
Requires-Dist: umbridge>=1.2; extra == "server"
Provides-Extra: mpi
Requires-Dist: mpi4py>=3.1; extra == "mpi"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid>=0.9; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# HydroBayesCal

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

[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue)](https://hydrobayescal.readthedocs.io)
[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-green)](LICENSE)

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) — fully supported
* **OpenFOAM** (interFoam) — binding under active development

Experimental design and parameter sampling are delegated to
[BayesValidRox](https://pages.iws.uni-stuttgart.de/inversemodeling/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.

```bash
pip install hydroBayesCal
```

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

```bash
git clone https://github.com/sschwindt/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](https://hydrobayescal.readthedocs.io/en/latest/installation.html)
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:

```bash
python bal_telemac.py --config config.py
```

See the [documentation](https://hydrobayescal.readthedocs.io) for the
end-to-end workflow, the configuration parameters, the code architecture, and
worked examples.

## Development & releases

Contributions are welcome — see [CONTRIBUTING.md](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](https://semver.org/) /
  [PEP 440](https://peps.python.org/pep-0440/); the version lives only in
  `pyproject.toml` (keep `docs/conf.py` in sync). PyPI versions are immutable —
  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](https://hydrobayescal.readthedocs.io/en/latest/references.html).

## License

Distributed under the BSD 3-Clause License. See [LICENSE](LICENSE).
