Using HydroBayesCal with TELEMAC

This page explains how to run a surrogate-assisted Bayesian calibration of a TELEMAC (2D/3D) model. It complements the generic Bayesian Calibration Workflow and the binding walk-through in TELEMAC & OpenFOAM Bindings.

Prerequisites 

A working TELEMAC v9 installation with its Python API reachable. Follow the installation guide at hydro-informatics.com/install-telemac and the HydroBayesCal Installation page for coupling the two environments.
A fully functional TELEMAC model that runs to completion on its own before you start any calibration.
HydroBayesCal installed in an environment that is loaded together with the TELEMAC environment variables (see Installation — env-scripts/activateHBCtelemac.sh).

Note

With TELEMAC v9 the solver is launched through telemac2d.py / telemac3d.py from the active systel configuration (pysource file). HydroBayesCal calls these launchers for you; you only need the combined environment loaded so that telemac2d.py is on the PATH.

The TELEMAC simulation folder 

Collect all files needed for one TELEMAC run into a single model directory (model_dir). A typical hydrodynamic setup contains:

File	Purpose
`*.cas`	Steering (control) file with the numerical configuration. Its name is passed as `control_file`.
`*.cli`	Boundary-condition file (type and location of the boundaries).
`*.slf`	SELAFIN geometry/mesh file.
`*.tbl`	Friction (roughness) table, required when calibrating friction zones (passed as `friction_file`).
`*.liq`	Liquid boundary conditions for unsteady flow (if applicable).
rating curve / stage-discharge	Outflow boundary definition (if applicable).

Before calibrating

Verify the model runs properly on its own.
Start from dry initial conditions once, then switch to fast-converging hotstart (wet) conditions to speed up the many surrogate-training runs.

Measurement / calibration points 

The calibration targets are provided in a CSV file (calibration_pts_file_path) with one row per measurement location. The header uses the coordinates and, for each calibration quantity, a <quantity>_DATA and a <quantity>_ERROR column (matched case-insensitively):

X, Y, WATER DEPTH_DATA, WATER DEPTH_ERROR, SCALAR VELOCITY_DATA, SCALAR VELOCITY_ERROR
...

The _ERROR column holds the measurement error in the physical units of the quantity. Measurements and the computational mesh (.slf) must use the same coordinate reference system so modelled and measured values can be compared.

TELEMAC-specific parameters 

In addition to the common Functioning of the HydroSimulations Class parameters, the TelemacModel class accepts:

Parameter	Description
`tm_xd`	Hydrodynamic solver: `"Telemac2d"` or `"Telemac3d"`.
`control_file`	Name of the `.cas` steering file (no path).
`friction_file`	Name of the `.tbl` friction file (no path); needed for friction zones.
`results_filename_base`	Base name of the results `.slf` file, updated for each run and used for output extraction.
`gaia_steering_file`	GAIA steering file for morphodynamics (optional).

Calibration parameters and TELEMAC keywords 

For TELEMAC, each entry of calibration_parameters must match a keyword in the model files:

Steering-file keywords must be written exactly as in the .cas file, using = (not :). See the TELEMAC user manuals.

calibration_parameters = ["LAW OF FRICTION ON LATERAL BOUNDARIES",
                          "INITIAL ELEVATION", "BOTTOM FRICTION"]

Friction zones are calibrated per zone; the zone names must be defined in the .tbl friction file, and each name must contain zone/Zone/ ZONE as a prefix. See friction (roughness) zones.
```
calibration_parameters = ["zone1", "zone2", "Zone3"]
```

calibration_quantities / extraction_quantities use SELAFIN variable names, e.g. "WATER DEPTH", "SCALAR VELOCITY", "TURBULENT ENERG", "VELOCITY U", "VELOCITY V", "CUMUL BED EVOL".

Note

Bayesian active learning only handles numeric (scalar) parameters. A parameter that takes a non-numeric value (e.g. a solver-type keyword) cannot be used as a calibration parameter.

Running the calibration 

Define a configuration file (see the example templates/config_Telemac.py) and launch the TELEMAC driver:

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

The driver builds a TelemacModel, sets up the experimental design, runs the initial simulations, trains the GPE and performs Bayesian Active Learning. Equivalently, in a script:

from hydroBayesCal.telemac.control_telemac import TelemacModel

model = TelemacModel(
    control_file="tel_model.cas",
    tm_xd="Telemac2d",
    friction_file="friction.tbl",
    results_filename_base="results",
    model_dir="/path/to/telemac_simulation",
    res_dir="/path/to/results",
    calibration_pts_file_path="/path/to/measurements-calibration.csv",
    n_cpus=8,
    init_runs=15,
    max_runs=30,
    calibration_parameters=["zone1", "zone2", "BOTTOM FRICTION"],
    param_values=[[0.011, 0.79], [0.011, 0.79], [0.018, 0.028]],
    calibration_quantities=["WATER DEPTH", "SCALAR VELOCITY"],
    extraction_quantities=["WATER DEPTH", "SCALAR VELOCITY", "TURBULENT ENERG"],
)

See TELEMAC & OpenFOAM Bindings for the full driver, the experiment-design and BAL functions, and the structure of the output folders.

Extract & compare 2d/3d simulation data 

During calibration, HydroBayesCal extracts model results at the calibration points through TelemacModel.extract_data_point. For TELEMAC-3D results, this extraction is depth-explicit: the routine reads the ELEVATION Z planes of the 3D SELAFIN file, reconstructs the vertical column above every horizontal point, and selects the vertical plane whose elevation is closest to the requested measurement height above the local bed. Horizontal sampling uses inverse-distance-weighted (IDW) interpolation over the k nearest mesh nodes (or the nearest node only), and the time series can be reduced to the last time step, a specific time step, or the mean of the last n steps.

The same functionality is available outside the calibration workflow through the top-level function hydroBayesCal.extract_results(). It works on any result file - a 2D SELAFIN file, a 3D SELAFIN file, the 2D file generated by a TELEMAC-3D run, or OpenFOAM VTK output - without a TelemacModel instance or configuration file:

import hydroBayesCal as hbc

# 3D TELEMAC results: extract the velocity magnitude 5 cm above the bed
# at two points; the closest vertical plane is selected per point
df = hbc.extract_results(
    "r3d_steady.slf",
    variable="velocity",           # or exact names, e.g. "VELOCITY U"
    x=[371522.5, 371540.0],
    y=[5345152.0, 5345170.0],
    z=0.05,                        # height above the local bed [m]
)
print(df)  # columns: point, x, y, z, plane, z_plane, z_above_bed, velocity

# Full vertical profile (one row per plane) by omitting z
profile = hbc.extract_results(
    "r3d_steady.slf",
    variable=["velocity", "VELOCITY W"],
    x=371522.5, y=5345152.0,
)

# 2D results work with the same call (z is ignored); time-averaging
# over the last 10 time steps with nearest-node sampling
df_2d = hbc.extract_results(
    "r2d_steady.slf",
    variable=["WATER DEPTH", "velocity"],
    x=[371522.5, 371540.0], y=[5345152.0, 5345170.0],
    time="mean_last", n_last=10, method="nearest",
)

The returned pandas.DataFrame has one row per point (or per point and vertical plane for a 3D profile), which makes model-to-model or model-to-measurement comparisons a simple DataFrame merge.

The variable argument accepts exact SELAFIN variable names (case-insensitive, e.g. "WATER DEPTH", "TURBULENT ENERG") and the aliases "velocity" (flow velocity magnitude: SCALAR VELOCITY or sqrt(U^2+V^2) in 2D, sqrt(U^2+V^2+W^2) in 3D) and "depth". An unknown name raises an error that lists the variables available in the file.

The function works analogously for OpenFOAM: pass a .vtu/.vtk file or a case directory containing the VTK/ folder written by foamToVTK. OpenFOAM results are inherently three-dimensional, so z is the absolute vertical coordinate and is required:

df_of = hbc.extract_results(
    "/path/to/openfoam_case",       # or .../VTK/case_1234/internal.vtu
    variable=["velocity", "k"],     # fields as written by foamToVTK
    x=[0.5, 0.7], y=[0.2, 0.2], z=[0.05, 0.05],
    time="mean_last", n_last=3,     # averages the last 3 VTK time steps
)

For the wall-law diagnostics of the calibration workflow (friction velocity, y-plus, and the complete modeled vertical velocity profile at each calibration point), see TelemacModel.extract_data_point with compute_wall_law_diagnostics=True in the API Reference.