Installation

HydroBayesCal is a Python package bound to an external numerical model (TELEMAC is fully supported, OpenFOAM is in progress, Delft3D-FLOW is planned). It is developed and tested on Debian/Ubuntu Linux, which we recommend: Linux gives the flexibility to configure the environment and TELEMAC together, and a command-line interface well suited to batch simulations. Windows has not been tested.

This page covers (1) the Python environment and the package itself, and (2) the numerical-model bindings.

Python environment 

Dependencies are declared once in pyproject.toml; the legacy requirements*.txt files simply install the project. Use a dedicated environment.

Important

HydroBayesCal requires Python >= 3.10 and is tested on CPython 3.10, 3.11 and 3.12. No upper bound is enforced, but newer interpreters are only supported once the dependency stack provides compatible wheels.

Option A — from PyPI (recommended)

Install the released package with pip (preferably into a fresh virtual environment):

python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install hydroBayesCal

The core install pulls the full surrogate/UQ stack (NumPy, SciPy, pandas, scikit-learn, PyTorch, GPyTorch, emcee, chaospy, PyVista and BayesValidRox).

Option B — conda / mamba (development)

A ready-made environment file is provided. From the repository root:

mamba env create -f environment.yml   # or: conda env create -f environment.yml
mamba activate hbenv

This creates a Python 3.11 environment and installs HydroBayesCal in editable mode with its documentation, mesh and model-server extras.

Option C — editable install from a clone 

HydroBayesCal uses a src layout and is installed like any modern Python package:

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

Optional feature sets (extras) can be added in brackets (e.g. pip install "hydroBayesCal[mesh]"):

Extra	Purpose
`mesh`	Extra mesh / geospatial IO (`vtk`, `meshio`, `rasterio`) for some post-processing utilities.
`server`	UM-Bridge model-server coupling (`umbridge`).
`mpi`	Parallel execution on HPC clusters (`mpi4py`; needs an MPI toolchain).
`docs`	Build this documentation (Sphinx + RTD theme + Mermaid).
`dev`	Development tooling (`pytest`, `build`, `twine`, `ruff`).

For example, a developer install with documentation and mesh tools:

pip install -e ".[dev,docs,mesh]"

Warning

Large download — multi-GB. Installing HydroBayesCal pulls in PyTorch, which on Linux x86_64 brings a full set of NVIDIA CUDA wheels (nvidia-cublas, nvidia-cudnn, nvidia-cusolver, triton …). Together these amount to several gigabytes, and they are downloaded even on machines without an NVIDIA GPU. On metered, disk-constrained or CPU-only systems, install the CPU build of PyTorch first, from its dedicated index, then install HydroBayesCal:

pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install hydroBayesCal

(pip keeps the already-installed CPU torch instead of fetching the CUDA build.) The vtk wheel pulled in via PyVista is also large (~hundreds of MB). On clusters without a working MPI toolchain, omit the mpi extra.

Numerical-model bindings 

TELEMAC 

Time requirement: ~60 min.

The calibration routines drive the open-source modelling system TELEMAC-Mascaret (TELEMAC 2D solves the depth-averaged shallow-water equations; TELEMAC 3D solves the Reynolds-averaged Navier–Stokes equations). Install it following the developers’ instructions at opentelemac.org, or the HydroBayesCal-tailored guide at hydro-informatics.com/install-telemac. We recommend the pysource.gfortranHPC.sh configuration (or your preferred pysource file).

Loading HydroBayesCal and TELEMAC together

Running a calibration needs both the HydroBayesCal environment and the TELEMAC environment variables active at once. The repository ships an activation template in env-scripts/activateHBCtelemac.sh.

Note

One-time setup — open env-scripts/activateHBCtelemac.sh in a text editor and set:

TELEMAC_CONFIG_DIR — your TELEMAC installation’s config directory.
TELEMAC_CONFIG_NAME — your TELEMAC configuration file name.
the path/name of your HydroBayesCal environment.

Each session — from the repository root, either source the script directly or use the convenience launcher:

source env-scripts/activateHBCtelemac.sh
# or
python activate_HBC_Telemac.py

A successful activation reports that both the HydroBayesCal and TELEMAC environments were loaded.

Verify the TELEMAC Python API is reachable:

python -c "import telapy; print(telapy.__version__)"

OpenFOAM 

Note

The OpenFOAM (interFoam) binding is under active development. It requires a working OpenFOAM installation on PATH (decomposePar, reconstructPar, the solver, and foamToVTK); see the installation guide at hydro-informatics.com/install-openfoam. The mesh extra (PyVista/VTK) is used to read the VTK output. See Using HydroBayesCal with OpenFOAM for running a calibration.

Delft3D-FLOW 

Note

The Delft3D-FLOW (Deltares) binding is planned and not yet implemented. A placeholder interface (hydroBayesCal.delft3d.control_delft3d.Delft3DModel) records the intended coupling and the Delft3D-specific file conventions (.mdf master definition file, config_d_hydro.xml / d_hydro launcher, NEFIS trim/trih output). It raises NotImplementedError. See Using HydroBayesCal with Delft3D-FLOW for the planned workflow.

Check your installation 

With the environment active, confirm the package imports:

python -c "import hydroBayesCal; print('HydroBayesCal OK')"

You are now ready to set up a calibration — continue with Bayesian Calibration Workflow.

Building and releasing (maintainers)

The project is configured for PyPI via pyproject.toml (src layout, SPDX license, build backend setuptools). The full contributor guide — including coding conventions and the release checklist — lives in CONTRIBUTING.md.

Versioning 

HydroBayesCal follows Semantic Versioning (MAJOR.MINOR.PATCH), a subset of PEP 440:

MAJOR — incompatible API changes,
MINOR — new, backward-compatible features (e.g. a new solver binding),
PATCH — backward-compatible bug fixes.

The version is declared once, as version in pyproject.toml; keep release/version in docs/conf.py in sync. Pre-1.0, the API may still change between minor versions.

Important

PyPI versions are immutable: an uploaded X.Y.Z can never be re-uploaded or overwritten (even after yanking). Always bump the version for a new release.

Releasing 

Releases are automated through GitHub Actions and PyPI Trusted Publishing (OIDC) — no API token is stored. The workflow (.github/workflows/publish.yml) runs when a GitHub Release is published:

Bump version in pyproject.toml (and docs/conf.py); commit and push to main.
On GitHub, draft a new Release, create the tag vX.Y.Z, and publish it.
The workflow builds the sdist + wheel, runs twine check, and publishes to PyPI via the trusted publisher.

Building locally 

To reproduce what CI does (without publishing):

pip install -e ".[dev]"          # provides build + twine
python -m build                  # creates dist/*.whl and dist/*.tar.gz
twine check dist/*               # validate the metadata/long description

A manual twine upload is only needed as a fallback when Trusted Publishing is unavailable (use a project-scoped token); see CONTRIBUTING.md.