Flux de travail, études et calage

axqua.dem.clip_dem_to_roi(cfg, dem_path, out_path=None)[source]

Clip dem_path to the configuration’s ROI boundary, in the project CRS.

Convenience wrapper around clip_to_roi() that takes the boundary and CRS from cfg. By default the clipped raster is written next to the source as <stem>-roi-clip.tif; pass out_path to choose another location. The output path is returned.

Paramètres:: cfg (Config)
Type renvoyé:: Path

axqua.dem.clip_dem(cfg, dem_path, out_name)[source]

Pipeline wrapper: clip dem_path to the ROI, reprojected to the project CRS.

Paramètres:

cfg (Config)
dem_path (Path)
out_name (str)

Type renvoyé:

ClippedDEM

axqua.dem.propagated_lod(sigma_initial, sigma_target, confidence_level=0.95)[source]

Minimum level of detection [m] from propagated survey uncertainty.

LoD = t * sqrt(sigma_initial^2 + sigma_target^2) (Brasington/Wheaton), the spatially-uniform propagated-error threshold below which a bed-elevation change is indistinguishable from survey noise at confidence_level.

Paramètres:

sigma_initial (float)
sigma_target (float)
confidence_level (float)

Type renvoyé:

axqua.dem.resolve_lod(cfg)[source]

Resolve the minimum level of detection [m] and a human-readable rationale.

Priority: an explicit dem_of_difference.min_lod > the propagated survey uncertainty (when both per-DEM uncertainties are given) > 0 (no thresholding).

Paramètres:: cfg (Config)
Type renvoyé:: tuple[float, str]

axqua.dem.dem_of_difference(cfg, initial, target)[source]

Compute target - initial on the initial ROI grid -> bed-change raster (m).

Applies the minimum level of detection (see resolve_lod()): cells whose absolute change is below the LoD are masked to nodata (dem_of_difference.mask_below_lod, the default) or set to 0. The net / erosion / deposition volumes over the significant cells are logged.

Paramètres:

cfg (Config)
initial (ClippedDEM)
target (ClippedDEM)

Type renvoyé:

axqua.dem.run(cfg)[source]

Execute stage 1; returns the produced raster paths.

Paramètres:: cfg (Config)
Type renvoyé:: dict[str, Path]

Débit données et courbes de tarage

Readers for hydraulic inputs: inflow, stage-discharge, and measurements.

Handles the Bavarian LfU (gkd.bayern.de) CSV export format (UTF-8 BOM, ;-separated, comma decimals, ~10 metadata lines, then a Datum;... header) as well as plain 2-column CSVs, so the workflow ingests both the raw gauge files in stage-discharge/ and tidy user-prepared tables.

class axqua.hydraulics.Inflow(times_s: 'np.ndarray | None', discharge: 'np.ndarray', steady_value: 'float')[source]

Bases : object

Paramètres:

times_s (np.ndarray | None)
discharge (np.ndarray)
steady_value (float)

times_s: np.ndarray | None

discharge: np.ndarray

steady_value: float

axqua.hydraulics.read_inflow(path, steady=True)[source]

Read an inflow discharge series (LfU or generic) into an Inflow.

Paramètres:

path (Path)
steady (bool)

Type renvoyé:

Inflow

axqua.hydraulics.read_rating_pairs(path)[source]

The pairs of a rating curve: (Q, WSE) as two arrays sorted by Q.

Paramètres:: path (Path)

axqua.hydraulics.read_stage_discharge(path)[source]

Read a rating curve -> callable mapping discharge (m3/s) to WSE (m).

Accepts a Q,WSE (or Q,stage) CSV with one or more rows. A single Q-h pair is enough for a steady run (the WSE is then constant); with several rows the WSE is linearly interpolated in Q. Querying a Q outside the tabulated range clamps to the nearest endpoint and logs a warning (the curve does not extrapolate), so for steady runs supply the pair at the simulated discharge.

Paramètres:: path (Path)

axqua.hydraulics.read_measurements(path, crs_epsg)[source]

Read hydraulic measurement points into a tidy DataFrame.

Returns columns: id, x, y, z (vertical offset, default 0), and any of water_depth / scalar_velocity that are present. Accepts a point shapefile/gpkg or a CSV with x/y columns.

Paramètres:

path (Path)
crs_epsg (int)

Type renvoyé:

pandas.DataFrame

axqua.hydraulics.resolve_outflow_wse(cfg, inflow_q)[source]

Downstream water-surface elevation for a prescribed-elevation outflow.

Shared by both backends: TELEMAC writes it as PRESCRIBED ELEVATIONS and OpenFOAM as a prghPressure profile on the outlet patch, and they must agree or the two models are not driven the same way.

stage_discharge (default) reads the rating curve and interpolates the WSE at the simulated discharge; elevation uses the fixed prescribed value.

Paramètres:: inflow_q (float)
Type renvoyé:: float

Generate an outflow stage-discharge rating curve from normal-flow hydraulics.

For a steady simulation the downstream (outflow) boundary needs the water-surface elevation at the simulated discharge. When no measured rating curve is available, this module synthesizes one from a roughness coefficient and a prismatic channel cross-section by inverting Manning’s uniform- (normal-) flow equation:

Q = (1 / n) * A(h) * R(h) ** (2/3) * sqrt(S0)

for a trapezoidal section with bottom width b and side slope m (horizontal:vertical, m = 0 is rectangular):

A(h) = (b + m * h) * h                      # flow area
P(h) = b + 2 * h * sqrt(1 + m ** 2)         # wetted perimeter
R(h) = A(h) / P(h)                           # hydraulic radius

Q is strictly increasing in depth, so the normal depth h_n conveying a given Q is found by bisection; the stage is WSE = bed_elevation + h_n.

Roughness is given either as a Manning n or a Strickler Kst (n = 1/Kst). The result is written as a Q,WSE,depth CSV that axqua.hydraulics. read_stage_discharge() consumes as boundaries.stage_discharge.

axqua.rating.normal_depth(discharge, *, manning=None, strickler=None, slope, bottom_width, side_slope=0.0, tol=1e-06)[source]

Normal (uniform-flow) depth [m] conveying discharge [m3/s].

Roughness via manning (n) or strickler (Kst). slope is the longitudinal bed slope S0 (m/m, > 0); bottom_width and side_slope (H:V) define the trapezoidal section. Solved by bisection on the (monotonic) Manning equation.

Paramètres:

discharge (float)
manning (float | None)
strickler (float | None)
slope (float)
bottom_width (float)
side_slope (float)
tol (float)

Type renvoyé:

axqua.rating.generate_stage_discharge(out, discharges, *, manning=None, strickler=None, slope, bottom_width, side_slope=0.0, bed_elevation=0.0)[source]

Write a normal-flow Q,WSE,depth rating CSV for discharges to out.

For a steady run a single discharge (the simulated Q) is enough; pass several to tabulate a curve. WSE = bed_elevation + normal_depth(Q).

Paramètres:

out (str | Path)
discharges (Iterable[float] | float)
manning (float | None)
strickler (float | None)
slope (float)
bottom_width (float)
side_slope (float)
bed_elevation (float)

Type renvoyé:

axqua.rating.synthesize_outflow_rating(cfg, discharge, *, side_slope=0.0, slope=None, bed_elevation=None, width=None, manning=None, strickler=None, out=None)[source]

Derive an outflow stage-discharge curve from the case geodata + config.

Unless given explicitly, the trapezoidal-channel parameters are taken from the geodata: width = total length of the outflow liquid-boundary line(s) (boundaries.liquid_boundaries, field tagged outflow); bed_elevation = thalweg (minimum DEM elevation) sampled along that line; slope = reach bed slope from a linear fit of the DEM along geodata.channel_centerline. The roughness defaults to the lateral-boundary friction in the config (friction.boundary_law/boundary_coefficient; Strickler or Manning). discharge is one discharge or several; writes a Q,WSE,depth CSV with one row per discharge to out (default boundaries.stage_discharge).

Paramètres:

side_slope (float)
slope (float | None)
bed_elevation (float | None)
width (float | None)
manning (float | None)
strickler (float | None)

Type renvoyé:

axqua.rating.stage_for_discharge(discharge, *, station, bed, ks, slope, freeboard=10.0)[source]

Water level [m] at which a surveyed cross-section conveys discharge.

Inverts the section conveyance (_section_conveyance()) by bisection between the section thalweg and its highest point plus freeboard. This is the normal (uniform-flow) stage of the section: the level at which the friction slope equals the bed slope.

Used both by section_rating() (one stage per requested discharge, written to a rating CSV) and by the pre-wet initial condition, which needs the normal stage of a whole sequence of cross-sections along the reach - see axqua.steering._normal_depth_prewet_surface().

axqua.rating.section_rating(out, discharges, *, station, bed, ks, slope, log_label='')[source]

Stage-discharge curve from a surveyed cross-section rather than a trapezoid.

station/bed are the along-section distance (m) and bed elevation (m) of the real section; ks is the Nikuradse roughness (m), a scalar or one value per station. Each requested discharge is turned into a stage by stage_for_discharge().

A trapezoidal idealisation of the same section (generate_stage_discharge()) puts the full width at the full depth, so it over-estimates the flow area at a given stage and returns a stage that is too low. On a V- or U-shaped natural section the error is large enough to force a supercritical drawdown at a prescribed-elevation outflow - the boundary pulls the level below the reach’s own normal depth and the flow accelerates through the outlet to satisfy continuity. Integrating the real section removes that artifact.

axqua.rating.synthesize_outflow_rating_from_section(cfg, discharge, *, slope=None, out=None, n_samples=300)[source]

Outflow rating from the DEM cross-section along the outflow boundary line.

Samples the bed along the outflow liquid-boundary line straight out of geodata.dem_initial, picks up the Nikuradse ks of the roughness zone each sample falls in (geodata.roughness_zones + roughness_table; the lateral friction.boundary_* roughness otherwise), takes the reach slope from a linear fit of the DEM along geodata.channel_centerline, and inverts the section conveyance with section_rating().

Paramètres:: n_samples (int)

Mesures de terrain

Ground-truth ingestion: field measurements -> tidy calibration tables.

Calibration ground truth comes in two halves that live in separate places and are joined here:

positions - a point layer (shapefile/GeoPackage) giving where each measurement was taken, in some CRS (often not the project CRS); reprojected to the project CRS on ingest.
values - the measured quantities, in a source-specific export (e.g. a SonTek FlowTracker2 .ft.sum workbook).

Every source is normalized to the same tidy schema: the first three columns are x, y, z (project CRS, meters), followed by quantity columns. For FlowTracker hydraulics these are u, v, w (velocity components, m/s), u_err, v_err, w_err (per-component error, m/s) and h (water depth, m).

FlowTracker is only one possible source; the tidy schema is generic so other ground-truth (e.g. ADCP, hand-held probes, sediment samples) can be added as further adapters without touching the calibration stage that consumes the tidy tables.

axqua.ground_truth.read_xlsx_sheet(path, sheet=0)[source]

Read one worksheet into a raw, header-less DataFrame.

Cells keep their string form except plain numbers, which are coerced to float. Robust to the styling that defeats pandas.read_excel/openpyxl.

Paramètres:

path (Path)
sheet (int | str)

Type renvoyé:

pandas.DataFrame

axqua.ground_truth.read_flowtracker_values(xlsx, sheet=None)[source]

Read a SonTek FlowTracker2 .ft.sum workbook -> per-vertical values.

Returns columns ID, u, v, w, u_err, v_err, w_err, h (one row per measurement vertical). Coordinates are not here - they come from the paired DGPS position layer (see read_flowtracker()).

sheet names a worksheet to read instead of the first. A profile sheet (several readings per vertical, headers suffixed raw) is detected by its own column names and returns one row per reading, keyed by the same ID - so a vertical appears several times and the caller must apply select_profile_rows().

Paramètres:

xlsx (Path)
sheet (str | int | None)

Type renvoyé:

pandas.DataFrame

axqua.ground_truth.read_flowtracker(xlsx, positions, crs_epsg, join_key='ID', *, sheet=None, profile='single', group_key=None)[source]

Join FlowTracker values to their DGPS positions -> tidy hydraulics table.

Paramètres:

xlsx (Path) – the .ft.sum export with the measured velocities/depths.
positions (Path) – point layer (shp/gpkg) of the survey points, with a matching join_key column; reprojected to crs_epsg for the x/y output.
crs_epsg (int) – project CRS the output coordinates are expressed in.
join_key (str)
sheet (str | int | None)
profile (str)
group_key (str | None)

Renvoie:

the tidy schema x, y, z then u, v, w, u_err, v_err, w_err, h.

Type renvoyé:

pandas.DataFrame

axqua.ground_truth.scalar_velocity(df)[source]

Depth-averaged scalar velocity magnitude from the components present.

Paramètres:: df (pandas.DataFrame)
Type renvoyé:: pandas.Series

axqua.ground_truth.read_points(path, crs_epsg)[source]

Read a point layer/CSV that already carries coords + quantities -> tidy.

A spatial layer (shp/gpkg/geojson) is reprojected to crs_epsg and its geometry becomes x, y; a CSV must provide x/y columns (or aliases). All other columns pass through (canonicalised where recognized).

Paramètres:

path (Path)
crs_epsg (int)

Type renvoyé:

pandas.DataFrame

axqua.ground_truth.VERTICAL_TOLERANCE = 0.01: Readings closer together than this in plan belong to one vertical [m]. A FlowTracker profile is taken with the rod standing in one place, so its readings share a position exactly; the tolerance only absorbs coordinate rounding.

axqua.ground_truth.select_point_profiles(df, rule='single', *, group_key=None)[source]

Apply a profile rule to a point layer that holds several readings per vertical.

A layer exported from a FlowTracker campaign has one point per reading: three points on top of each other where a vertical was sampled at 0.2, 0.6 and 0.8 of the depth. A depth-averaged model has one value there, so the readings of a vertical are reduced by the same rules as a FlowTracker workbook (select_profile_rows()) - by default the reading nearest 0.6 of the depth.

The vertical is named by group_key where the layer has such a column, and otherwise by the position itself. A layer with one reading per position comes back unchanged, which is every layer this function did not exist for.

Paramètres:

df (pandas.DataFrame)
rule (str)
group_key (str | None)

Type renvoyé:

pandas.DataFrame

axqua.ground_truth.compile_ground_truth(cfg)[source]

Compile the configured raw sources into the tidy multi-tab table.

Sources sharing a category are concatenated into one sheet; a filled calibration-target template (ground_truth.targets) contributes its hydraulics / morphodynamics tabs the same way. Returns the written path (cfg.ground_truth_path), or None when neither is configured (the user supplies the tidy table directly).

Type renvoyé:: Path | None

axqua.ground_truth.read_tidy(path)[source]

Read the tidy multi-tab ground-truth table -> {category: DataFrame}.

Each sheet/file becomes one category; columns are canonicalised and any quantity columns absent from a given dataset are simply not present (callers must tolerate missing quantities).

Paramètres:: path (Path)
Type renvoyé:: dict[str, pandas.DataFrame]

axqua.ground_truth.write_tidy(tables, path)[source]

Write {category: DataFrame} to a multi-tab xlsx (one sheet per category).

Paramètres:

tables (dict[str, pandas.DataFrame])
path (Path)

Type renvoyé:

axqua.ground_truth.DEFAULT_RELATIVE_HEIGHT = 0.4: Height above the bed, as a fraction of the column, of the conventional « 0.6 depth » point. 0.6 is measured DOWN FROM THE SURFACE (that is the FlowTracker/USGS convention), so the probe sits at 0.4 of the depth ABOVE the bed. Getting this backwards misplaces every target by 0.2*h.

axqua.ground_truth.relative_height(df, *, default=0.4)[source]

Height above the bed as a fraction of the column, per measurement row.

Returns (f, source); source names which rule fired, so a placement audit can say where every target’s position came from rather than leaving it implicit. First hit wins:

an explicit f column;
h_meas and h -> 1 - h_meas/h (FlowTracker MeasD/FinalD);
pct_depth -> 1 - pct_depth (% Depth, also from the surface);
a label ending -<p>h (the q47-3-1501-0.93h convention);
default, with one warning naming how many rows took it.

Paramètres:

df (pandas.DataFrame)
default (float)

Type renvoyé:

tuple[pandas.Series, str]

axqua.ground_truth.select_profile_rows(df, rule='single', *, group_key='ID')[source]

Reduce a multi-depth profile table to the rows that become targets.

A FlowTracker vertical may carry several readings at different depths. Which of them a calibration should see is a modeling decision, not a data property, so it is named explicitly:

single: one row per vertical - the reading nearest the conventional 0.6 depth. The default, and a no-op when there is already one row per vertical, so every existing config keeps its present behavior.
all: every reading, one target each.
drop-lowest: every reading except the one nearest the bed, and only where there is more than one - a lone reading is kept. The near-bed reading sits inside the grain roughness on a coarse bed (KB15: 0.055 m above a bed with ks = 0.089 m), where a wall function returns a boundary condition rather than a result.
depth-average: one row per vertical carrying the USGS three-point depth-averaged velocity (u_0.2 + 2*u_0.6 + u_0.8) / 4 where three readings allow it, else the plain mean. This is the quantity a depth-averaged 2D model actually predicts.

The lowest reading is found by height above the bed, never by row order: the readings of one vertical arrive in whatever order they were entered (KB15 vertical 1501 reads 0.926, 0.540, 0.292 of the depth from the surface), and the source workbook has a column literally called entry order fixed.

Paramètres:

df (pandas.DataFrame)
rule (str)
group_key (str)

Type renvoyé:

pandas.DataFrame

Is the compiled ground truth’s elevation plausible against the model?

This module exists because of one defect that cost a calibration campaign. Inn KB15’s ground truth was joined to a DGPS layer whose z is the GNSS antenna elevation rather than the bed, so every target sat 2.26-2.70 m above the water. Nothing complained: HydroBayesCal’s OpenFOAM binding finds the nearest extraction point with no distance cutoff, so it returned a plausible-looking 0.003 m/s and the surrogate trained on it. The error was only visible as a failed calibration.

The discriminator is the whole point. A reach can legitimately have a biased DEM - KB15’s is 0.3 m high in the wetted channel from bathymetric-LiDAR attenuation - so « the residual is large » cannot be the test. What separates the two is shape:

an un-subtracted instrument height is a constant. Every point in the group is offset by the same rover-pole length, so the residual is large, tight, and flat in depth;
a physical bed bias grows with the water column (attenuation integrates along the light path), so the residual has a significant slope against depth.

On KB15 the two signatures are ~30 sigma apart, so the thresholds below are not delicately tuned. The depth-proportional case is reported and named, never silenced, because it is real and the reader needs to know it is there.

axqua.ground_truth_qa.OFFSET_THRESHOLD = 0.3: A residual must exceed this to be worth reporting at all [m].

axqua.ground_truth_qa.SIGMA_RATIO = 4.0: …and be at least this tight, relative to its own scatter, to be called constant.

axqua.ground_truth_qa.CONSTANT_TOLERANCE = 0.06: …with scatter no larger than this [m].

axqua.ground_truth_qa.REFUSE_THRESHOLD = 1.0: Above this, a constant residual is an error even under warn - a meter of « bed » error in a wadeable reach is never data.

axqua.ground_truth_qa.MIN_GROUP = 5: Fewer points than this cannot support the statistics.

class axqua.ground_truth_qa.ElevationFinding(severity: "Literal['error', 'warning', 'info']", code: "Literal['instrument-height', 'depth-proportional-bias', 'above-water-surface', 'outside-domain', 'mixed']", group: 'str', n: 'int', offset: 'float', slope: 'float', slope_p: 'float', scatter: 'float', message: 'str')[source]

Bases : object

Paramètres:

severity (Literal['error', 'warning', 'info'])
code (Literal['instrument-height', 'depth-proportional-bias', 'above-water-surface', 'outside-domain', 'mixed'])
group (str)
n (int)
offset (float)
slope (float)
slope_p (float)
scatter (float)
message (str)

severity: Literal['error', 'warning', 'info']

code: Literal['instrument-height', 'depth-proportional-bias', 'above-water-surface', 'outside-domain', 'mixed']

group: str

n: int

offset: float

slope: float

slope_p: float

scatter: float

message: str

line()[source]

Type renvoyé:: str

axqua.ground_truth_qa.reference_bed(cfg, x, y)[source]

The model bed, else the DEM, else nothing. Never raises.

Type renvoyé:: tuple[numpy.ndarray, str] | tuple[None, str]

axqua.ground_truth_qa.check_ground_truth_elevations(cfg, *, tables=None)[source]

Compare the compiled ground truth’s z with the model bed or the DEM.

Type renvoyé:: list[ElevationFinding]

axqua.ground_truth_qa.report(findings, *, strict=False, source='')[source]

Log the findings; raise under strict if any is an error.

Paramètres:

strict (bool)
source (str)

Type renvoyé:

None

Calibration-target template: a user-friendly calibration-target-data.xlsx.

Ground-truth data for the Bayesian calibration needs a consistent structure: measured values keyed by unique IDs that link to point layers (GeoPackage / shapefile) in user-sources/geodata/, so positions (surveyed once, in some CRS) and values (typed into a spreadsheet) stay cleanly separated but joinable.

This module writes and reads that structure:

write_target_template() generates the template workbook (default user-sources/ground-truth/calibration-target-data.xlsx) with four tabs:
- hydraulics - one row per measurement vertical: ID (or explicit x/y), velocity components u_x, u_y, u_z, the horizontal magnitude U_h (auto = sqrt(u_x^2 + u_y^2), live Excel formula), the RMS turbulent fluctuations u_x', u_y', u_z', U_h', TKE (auto proxy 0.5*(u_x”^2 + u_y”^2 + u_z”^2) when not measured directly), water depth and bottom elevation.
- morphodynamics - grain-size characteristics per sample point (d16..d90 [mm], fine fraction < 1 mm) plus a dz DoD column that is auto-filled on ingest from the DEM-of-Difference raster whenever the case provides one (geodata.dem_target / geodata.dem_of_difference).
- parameters - the calibration parameters: a drop-down over the parameter catalog, a zone/class column, the current value, min/max test range, and a tips column (live lookup of the catalog’s typical ranges). Rows for the case’s friction zones (from geodata.roughness_zones + roughness_table) are prefilled with their current ks.
- parameter-catalog - the reference table of calibration-relevant TELEMAC-2D / TELEMAC-3D / GAIA keywords with default ranges and tips; feeds the drop-down and the tips lookup.
read_targets() ingests the filled template into the tidy ground-truth tables (joining IDs to the configured position layers, reprojected to the project CRS; grain sizes converted mm -> m; DoD sampled at the sample points).
read_target_parameters() turns the parameters tab into CalibrationParameter rows with HydroBayesCal names (zone<N>, gaia<KEYWORD> <class>, or the literal TELEMAC keyword).

The template stays robust to Excel quirks: ingest never trusts the cached formula results for derived quantities (U_h, U_h', TKE are recomputed from the components when blank), and the workbook is read with the zip-level reader from axqua.ground_truth.

class axqua.targets.ParameterSpec(label: 'str', module: 'str', keyword: 'str', per_class: 'str', vmin: 'float', vmax: 'float', tips: 'str')[source]

Bases : object

Paramètres:

label (str)
module (str)
keyword (str)
per_class (str)
vmin (float)
vmax (float)
tips (str)

label: str

module: str

keyword: str

per_class: str

vmin: float

vmax: float

tips: str

hbc_name(klass)[source]

HydroBayesCal parameter name for this spec (and zone/class number).

Paramètres:: klass (int | None)
Type renvoyé:: str

axqua.targets.catalog_by_label()[source]

Type renvoyé:: dict[str, ParameterSpec]

axqua.targets.write_target_template(cfg, path=None, force=False)[source]

Write the calibration-target-data.xlsx template for this case.

Prefills the parameters tab with the case’s friction zones (current ks from geodata.roughness_table) and, when morphodynamics is on, a Shields row per configured sediment class; wires the parameter drop-down and the live tips lookup to the parameter-catalog sheet; declares the DoD status on the morphodynamics tab. Refuses to overwrite an existing (possibly user-filled) file unless force.

Paramètres:

cfg (Config)
path (Path | None)
force (bool)

Type renvoyé:

axqua.targets.read_targets(cfg)[source]

Ingest the filled template -> tidy tables {category: DataFrame}.

hydraulics: x, y, z then u, v, w, u_mag, u_std, v_std, w_std, u_mag_std, tke, h - blank derived cells (u_mag, u_mag_std, tke) are recomputed from the components.
morphodynamics: x, y, z then d16..d90 (converted mm -> m), fine_fraction and dz (auto-sampled from the DoD raster).

Paramètres:: cfg (Config)
Type renvoyé:: dict[str, pandas.DataFrame]

axqua.targets.read_target_parameters(cfg)[source]

Read the parameters tab into HydroBayesCal calibration parameters.

Rows need a parameter (drop-down label, else a literal TELEMAC keyword) and a numeric Min < Max; incomplete rows are skipped with a warning. Names follow HydroBayesCal’s convention (zone<N> for friction zones, gaia<KEYWORD> <class> for GAIA, the literal keyword otherwise).

Paramètres:: cfg (Config)
Type renvoyé:: list[CalibrationParameter]

FlowTracker2 -> calibration-target hydraulics tab.

Reads SonTek FlowTracker2 exports and writes one row per measurement point into the hydraulics tab of a calibration-target-data.xlsx template, keyed by each point’s own ID (which then joins the DGPS point layer in user-sources/geodata/, see axqua.targets).

Per point it extracts the three velocity components and their turbulent RMS fluctuations:

u_x, u_y, u_z <- the reported mean components VelX/VelY/VelZ (aka v(x)/v(y)/v(z)).
u_x', u_y', u_z' (RMS fluctuations) <- the sample standard deviation u std / Std Dev v'(x) / sigma_x. These are NOT the ``VxErr`` columns: VxErr is the FlowTracker standard error of the mean (the velocity measurement uncertainty), i.e. ~``std / sqrt(Npts)``. When only a plain .ft.sum summary is available (VxErr + Npts but no std-dev column), the RMS is reconstructed as u' ~ VxErr * sqrt(Npts).

TKE is taken from a measured column when present, else left to the template’s live formula 0.5*(u_x'^2 + u_y'^2 + u_z'^2); the water depth is the local total/final depth. U_h and U_h' recompute from the components.

Three export layouts are auto-detected by their headers:

SonTek ``.ft.sum`` (ID, MeasD, Npts, VelX/VelY/VelZ, VxErr/VyErr/VzErr, FinalD): only stderr -> RMS reconstructed.
TKE-stats export (VelX... plus u std/v std/w std): real RMS.
FT_TKE_Summary (Point, v(x)..., Std Dev v'(x)..., TKE [m2/s2]): real RMS + measured TKE; multiple worksheets scanned.

axqua.flowtracker.read_flowtracker(path, *, sheet=None, reconstruct_rms=True)[source]

Read one FlowTracker2 export -> per-point velocity/fluctuation table.

Returns columns ID, u, v, w, u_std, v_std, w_std, tke, depth (one row per measurement point). All worksheets that look like a FlowTracker table are scanned and concatenated unless sheet restricts to one (name or 0-based index). With reconstruct_rms the RMS fluctuations are filled from VxErr * sqrt(Npts) where a direct std-dev column is absent.

Paramètres:

path (Path)
sheet (str | int | None)
reconstruct_rms (bool)

Type renvoyé:

pandas.DataFrame

axqua.flowtracker.read_flowtrackers(paths, *, reconstruct_rms=True)[source]

Read and concatenate several FlowTracker2 exports (e.g. day1 + day2).

Paramètres:: reconstruct_rms (bool)
Type renvoyé:: pandas.DataFrame

axqua.flowtracker.fill_template_hydraulics(template, sources, *, sheet_name='hydraulics', start_row=2, reconstruct_rms=True)[source]

Write FlowTracker points into the template’s hydraulics tab, keyed by ID.

sources is one path or a list of FlowTracker2 exports. Existing rows in the tab are cleared first (so re-running is idempotent). u_x/u_y/u_z and u_x'/u_y'/u_z' are written; U_h, U_h' and (unless a measured TKE is present) TKE keep their live formulas; the water depth is filled. Returns the number of points written.

Paramètres:

template (Path)
sheet_name (str)
start_row (int)
reconstruct_rms (bool)

Type renvoyé:

axqua.flowtracker.write_driver_script(path, force=False)[source]

Drop the extract_flowtracker.py driver next to the template.

Paramètres:

path (Path)
force (bool)

Type renvoyé:

Path | None

Physical-flume measurements as cross-section reference data.

A laboratory campaign on a scale model does not produce what axqua.ground_truth expects. There are no coordinates and no point cloud: there are a handful of cross-sections, each with a mean water depth and a maximum velocity, at a few steady discharges. Comparing those against a model means comparing aggregates along a section with aggregates along the same section - not a modeled value at a point against a measured value at a point, which is what the calibration CSV would otherwise imply.

This module reads such a campaign into a tidy per-section table. The model side of the comparison is axqua.solvers.telemac.sections.section_statistics(), which reduces a result file over the same section lines, and compare() puts the two side by side.

Scale

A flume is usually a scale model, and Froude similarity scales the two quantities differently: at a length scale L (prototype:model), lengths go as L and velocities as sqrt(L). Which of the two conventions a published table is already in is a property of that table, not something to infer, so both scales are explicit arguments here and neither is guessed. read_depths() and read_velocities() report the convention they were given, and compare() records it in its output, so a comparison can never quietly be between a prototype model and a model-scale measurement.

axqua.labdata.DISCHARGE_LABELS = {'HQ': 1.0, 'HQ100': 1.0, 'MQ': 0.135, 'Q30': 0.06}: discharge labels used in the flume campaign, and what they mean in the prototype

axqua.labdata.LABEL_ALIASES = {'HQ': 'HQ100', 'HQ_100': 'HQ100', 'Q100': 'HQ100'}: The same discharge is spelled differently on different sheets of one campaign - the published depth summary says HQ100 where the velocity summary says HQ. Left alone, the two tables simply fail to join and half the reference data disappears into unmatched rows, which is the quiet kind of wrong.

axqua.labdata.canonical_label(label)[source]

One spelling per discharge, so sheets of the same campaign join.

Paramètres:: label (str)
Type renvoyé:: str

axqua.labdata.froude_velocity_scale(length_scale)[source]

Velocity scale under Froude similarity for a given length scale.

Paramètres:: length_scale (float)
Type renvoyé:: float

axqua.labdata.read_depths(path, *, sheet=0, length_scale=1.0)[source]

Read the flume water-depth summary into one row per discharge and section.

The sheet is a stack of blocks, one per discharge: a title row naming the discharge (Q30 - 60 L/s) whose remaining cells are the section labels (XS1 - US2), then a MEAN row and a standard-deviation row, both in millimeters. Depths are returned in meters, multiplied by length_scale.

Returns a list of dicts with discharge_label, discharge, section, station, h_mean, h_std.

Paramètres:

path (Path)
length_scale (float)

Type renvoyé:

list[dict]

axqua.labdata.read_velocities(path, *, sheet=0, velocity_scale=1.0)[source]

Read the flume velocity summary into one row per discharge and section.

The sheet is one table with a Discharge column filled only on the first row of each block, a section column, and the time-averaged maxima with their standard deviations. Velocities are returned in m/s, multiplied by velocity_scale.

Returns dicts with discharge_label, discharge, section, u_max, u_std, u3d_max, u3d_std and u_section_mean. A section where the ADV could not measure - too shallow, in this campaign - yields None rather than a row that looks measured.

Paramètres:

path (Path)
velocity_scale (float)

Type renvoyé:

list[dict]

axqua.labdata.reference_table(depths, velocities=None)[source]

Merge the depth and velocity readings into one row per discharge and section.

Paramètres:

depths (list[dict])
velocities (list[dict] | None)

axqua.labdata.compare(reference, modelled, *, length_scale=1.0, velocity_scale=1.0)[source]

Put measured section aggregates next to modeled ones.

modeled is the output of section_statistics() for the same sections, carrying a name that matches the reference section. The scales are recorded in the result so a table can never be read without knowing which convention the measurements were in.

Paramètres:

length_scale (float)
velocity_scale (float)

axqua.labdata.write_comparison(table, path)[source]

Write a comparison table, with the scale convention in the header comment.

Paramètres:: path (Path)
Type renvoyé:: Path

How much of a model-data mismatch is just not knowing where the point is.

A calibration compares a measured value against the model sampled at the measurement’s coordinates. That comparison silently assumes the coordinates are exact. When they are not, the model is read at the wrong place and the difference is charged to the model - or, worse, to whichever parameter happens to move it.

This is not a hypothetical. Inn KB15’s September-2025 survey was positioned with an RTK float solution rather than a fixed one, which is decimeter-to-metre horizontal rather than centimeter. On that reach the modeled water depth at the survey verticals is 0.374 m while the deepest node within 3 m is 0.648 m, so a position error of a few meters moves the modeled depth by more than the entire model-data discrepancy being calibrated against.

The fix is not to relocate the points. Their true positions are unknown, and snapping them to wherever the model happens to agree would manufacture agreement and calibrate nothing. The fix is to state the uncertainty honestly: if the point is known only to within sigma, then the model value at that point is uncertain by however much the model varies over sigma. That uncertainty is added in quadrature to the measurement error, so a target sitting on a steep gradient carries wide error bars and a target in a uniform patch carries narrow ones - which is exactly the weighting a likelihood should give them.

The spread is measured by sampling, not by a gradient. A gradient is a local linearisation, and the fields that make this matter - depth near a bank, velocity at a shear layer - are precisely the ones where a linearisation is worst over a meter-scale radius. Sampling a ring at the uncertainty radius costs nothing here (the sampler is a KD-tree lookup) and stays honest on a step.

axqua.positional_error.GNSS_SIGMA = {'dgps': 1.0, 'rtk-fixed': 0.03, 'rtk-float': 1.0, 'standalone': 3.0}: Horizontal sigma [m] for common GNSS solution qualities. These are working figures for judging a survey, not a specification of anyone’s receiver: a float solution in particular degrades with baseline, sky view and occupation time, and is the one quality where quoting a single number is least defensible.

axqua.positional_error.RING_POINTS = 8: Points on the sampling ring(s). Eight is enough to catch a one-sided step without making the sampler the cost of the calibration.

axqua.positional_error.sample_spread(sample, x, y, sigma, *, radii=(0.5, 1.0), ring_points=8)[source]

Spread of sample over the positional uncertainty, per point.

sample maps (xs, ys) to model values. The field is read at each point and on rings at radii multiples of sigma; the returned value is the standard deviation over those samples - an estimate of how much the model value could differ purely because the coordinates are uncertain.

Non-finite samples (a point that falls dry, or outside the mesh) are dropped rather than propagated, so a vertical near the waterline still gets a spread from the samples that did land in water.

Paramètres:

sample (Callable[[numpy.ndarray, numpy.ndarray], numpy.ndarray])
sigma (float)
radii (Sequence[float])
ring_points (int)

Type renvoyé:

numpy.ndarray

axqua.positional_error.telemac_sampler(geometry, results, variable)[source]

A nearest-node sampler for one SELAFIN variable.

Nearest-node rather than P1: a result merged from a parallel run is not a clean triangulation (it carries coincident nodes and zero-area triangles at the subdomain interfaces), and the question here is how much the field varies over meters - which nearest-node answers perfectly well on a sub-metre mesh.

Paramètres:: variable (str)
Type renvoyé:: Callable[[numpy.ndarray, numpy.ndarray], numpy.ndarray]

axqua.positional_error.describe(sigma, quality=None)[source]

One line naming the uncertainty and where it came from.

Paramètres:

sigma (float)
quality (str | None)

Type renvoyé:

str

axqua.positional_error.resolve_sigma(cfg)[source]

(sigma, quality) from ground_truth.position_quality / position_sigma.

An explicit sigma wins over a named quality, so a survey whose real accuracy is known does not have to be described by a lookup table.

Type renvoyé:: tuple[float, str | None]

Deriving the transform that puts CAD-local geometry on the map.

An STL carries no coordinate system - the format has no field for one. The drawing the STL was exported from usually does, because a construction drawing is set out in the national grid. So the transform is recoverable by matching the two: the same structure, drawn twice, once in meters of the map and once in whatever the CAD file used.

What can honestly be recovered, and what cannot

Matching two axis-aligned bounding boxes gives scale and translation reliably, and rotation only up to the ambiguity of a rectangle - a footprint rotated by 90 degrees has the same bounding box with its sides swapped, and one rotated by 180 has exactly the same box. This module therefore reports candidates and asks for a decision rather than picking one: it prints both boxes, the size ratio, the aspect agreement and the rotations that would align them, and leaves the choice to someone who can look at the result in QGIS. Silently choosing would produce a model that is plausible, wrong, and hard to catch later.

The honest fallback is the identity: run the case in the drawing’s own coordinates. The model is physically identical and only its position on a map is missing, which matters for a fish pass far less than it would for a river reach.

axqua.georef.COMMON_SCALES = ((1.0, 'metres'), (0.001, 'millimetres'), (0.01, 'centimetres'), (0.3048, 'feet')): scales a CAD drawing plausibly uses, as (factor, what it means)

class axqua.georef.Match(transform, cad_bounds, map_bounds, scale_ratio, aspect_cad, aspect_map, rotation_candidates=<factory>, verdict='unavailable', message='', recommendation='')[source]

Bases : object

A proposed georeferencing, with everything needed to judge it.

Paramètres:

transform (Transform)
cad_bounds (tuple)
map_bounds (tuple)
scale_ratio (float)
aspect_cad (float)
aspect_map (float)
rotation_candidates (list[float])
verdict (str)
message (str)
recommendation (str)

transform: Transform

cad_bounds: tuple

map_bounds: tuple

scale_ratio: float

aspect_cad: float

aspect_map: float

rotation_candidates: list[float]

verdict: str = 'unavailable'

message: str = ''

recommendation: str = ''

as_yaml()[source]

The surfaces keys this match implies, ready to paste into a config.

Type renvoyé:: str

axqua.georef.read_dxf_bounds(path, *, layers=None)[source]

Bounding box of a DXF drawing, in its own (map) coordinates.

GDAL’s DXF driver reads the entities as ordinary features, so this needs no CAD library. layers filters by the Layer attribute, which is how a drawing full of dimension lines, hatches and title blocks is reduced to the structure itself - without it the box is the box of the sheet, not of the building.

Paramètres:

path (Path)
layers (list[str] | None)

axqua.georef.dxf_layers(path)[source]

Every layer of a DXF with its feature count, for choosing what to match on.

Paramètres:: path (Path)
Type renvoyé:: list[tuple[str, int]]

axqua.georef.match(stl, dxf, *, layers=None, rotation_deg=None, dz=0.0)[source]

Propose a transform placing stl where dxf says the structure is.

The scale comes from the ratio of the two footprints” diagonals, snapped to a common CAD unit when it is within 2 % of one - a drawing is in millimeters or it is not, and 0.00098 is the former measured through a bounding box that includes a kerb. The rotation is not solved for: the candidates that could align the boxes are reported, and rotation_deg selects one. The translation then follows from the box centers, which is exact once scale and rotation are fixed.

Paramètres:

stl (Path)
dxf (Path)
layers (list[str] | None)
rotation_deg (float | None)
dz (float)

Type renvoyé:

Match

axqua.georef.parse_control_point(text)[source]

"12.5,40.0:4473100.2,5332090.7" -> the CAD pair and the map pair.

Paramètres:: text (str)
Type renvoyé:: tuple[tuple[float, float], tuple[float, float]]

axqua.georef.match_control_points(stl, points, *, dz=0.0)[source]

Fit a transform from control points, with the residuals that judge it.

The residuals are the whole point of reporting rather than applying: two points always fit exactly, so a third is what tells you whether the pairs were identified correctly. A meter of residual on a fish pass means a point was mis-picked.

Paramètres:

stl (Path)
points (list[str])
dz (float)

Type renvoyé:

Match

axqua.georef.log_control_points(stl, result)[source]

Narrate a control-point fit, and say where the geometry lands under it.

Paramètres:

stl (Path)
result (Match)

Type renvoyé:

Match

axqua.georef.report_control_points(stl, points, *, dz=0.0)[source]

The control-point path as a CLI return code. Kept for direct callers.

Paramètres:

stl (Path)
points (list[str])
dz (float)

Type renvoyé:

axqua.georef.log_match(result, logger_obj=None)[source]

Log a match() for a human to accept or reject; returns it unchanged.

Paramètres:: result (Match)
Type renvoyé:: Match

Étapes partagées des scripts cas

Shared workflow helpers for the per-case scripts.

The per-case preprocessing.py / initial_run.py / mesh_convergence_study.py are deliberately thin: the logic they have in common lives here so it is written once and stays identical across every case (template, example-Inn, ering-revised, …).

The central rule is that the steady discharge and the outflow stage prescription come from the case’s own ``case-config.yml``, never from a constant hard-coded in a script. prepare_steady_inputs() reads boundaries.prescribed_flowrate (or the inflow series) so each case uses its own configured boundary conditions; an explicit discharge= only overrides it when a script genuinely needs to.

axqua.workflow.resolve_discharge(cfg, discharge=None)[source]

Steady discharge [m3/s] the case is built for.

Resolution order: an explicit discharge argument, then the case config’s boundaries.prescribed_flowrate (the inflow Q set in case-config.yml), then the mean of the inflow series in boundaries.inflow. Raises when none of these is available - so a case never silently inherits another case’s discharge.

Paramètres:

cfg (Config)
discharge (float | None)

Type renvoyé:

axqua.workflow.synthesize_constant_inflow(cfg, discharge)[source]

Write a tiny constant-Q inflow series when boundaries.inflow is missing, point the config at it, and return its path (the existing inflow otherwise).

Paramètres:

cfg (Config)
discharge (float)

Type renvoyé:

axqua.workflow.synthesize_rating_if_missing(cfg, discharge, side_slope=1.0)[source]

Synthesize the outflow stage-discharge rating from the geodata when the stage_discharge outflow condition is active and no rating CSV is given.

Width comes from the outflow boundary line, bed + reach slope from the DEM and roughness from friction.boundary_* (see synthesize_outflow_rating()). Returns the rating path (existing or generated), or None for the other outflow conditions (elevation / free), which need no rating curve.

Paramètres:

cfg (Config)
discharge (float)
side_slope (float)

Type renvoyé:

Path | None

axqua.workflow.prepare_steady_inputs(cfg, discharge=None, *, side_slope=1.0, prewet_depth=<object object>)[source]

Configure the steady boundary conditions for a build and return the discharge.

Prescribes the steady discharge (from the config, see resolve_discharge()), synthesizes a constant inflow series and the outflow stage-discharge rating when those inputs are missing, so the build draws the inflow Q (m3/s) and the outflow stage (H) straight from case-config.yml. Used by preprocessing.py and the mesh-convergence study so they share one source of truth for the steady setup.

prewet_depth defaults to the sentinel « leave it as the config has it »; pass a float (or None) to set initialization.prewet_depth - the mesh-convergence study hotstarts the channel this way, the dry-start initial run leaves it untouched.

Paramètres:

cfg (Config)
discharge (float | None)
side_slope (float)
prewet_depth (float | None)

Type renvoyé:

axqua.workflow.format_flux_convergence(fc)[source]

Render a FluxConvergence result as user-facing report lines (whether the boundary fluxes reached mass balance, the hotstart time-step recommendation, and the produced csv/png paths).

Kept here so every case’s initial_run.py prints the convergence summary the same way; the analysis itself lives in axqua.flux_convergence.

Type renvoyé:: list[str]

axqua.workflow.format_3d_cases(setups)[source]

Render axqua.threed.build_3d_cases() results as user-facing report lines (one block per steering file; a None setup reports why it was skipped).

Kept here so every case’s add3d.py prints the same summary; the builders live in axqua.threed / axqua.unsteady.

Paramètres:: setups (dict)
Type renvoyé:: list[str]

axqua.workflow.expected_duration(cfg)[source]

Total simulated time [s] the run marches to when no stop criterion fires.

Mirrors axqua.steering’s DURATION logic: the explicit hydrodynamics.duration when set, else the n_time_steps * time_step fallback. Used to scale the solver progress bar (the variable time step makes the number of steps unknown a priori, so progress is measured against the simulated-time cap instead).

Paramètres:: cfg (Config)
Type renvoyé:: float

axqua.workflow.run_solver_streaming(runtime, cfg, *, cas_file=None, solver=None, ncsize=None, cwd=None, duration=None, show_progress=True, sink=None, should_stop=None)[source]

Run the TELEMAC solver, echoing its listing live with a progress bar.

Unlike a plain TelemacRuntime.run_solver(), this streams the solver’s stdout/stderr to the console as the run marches (so it is not silent) and, when show_progress, overlays a simulated-time progress bar parsed from TELEMAC’s listing header. The bar’s end time is duration when given (pass it whenever the .cas does not march to the config’s own time cap - e.g. a per-layer 3D run or a hydrograph-spanning unsteady run), else expected_duration(). cwd overrides the run folder (default cfg.model_dir - the convergence studies run each level in its own subfolder). Returns the CompletedProcess (its returncode reports success/failure; a non-zero exit does not raise). A run that TELEMAC-2D ended itself because a value left its limits comes back as a failure too, although TELEMAC reports it as a correct end: see _fail_on_limit_stop().

sink is an event sink (axqua.jobs.events): the same parsed iteration and simulated time that drive the terminal bar are also emitted as structured progress, so a detached job never asks anyone to parse a console log. should_stop is polled between lines and terminates the whole solver process group when it returns true.

Paramètres:

runtime (TelemacRuntime)
cfg (Config)
cas_file (str | None)
solver (str | None)
ncsize (int | None)
cwd (Path | str | None)
duration (float | None)
show_progress (bool)
sink (object | None)

axqua.workflow.LIMIT_STOP_CODE = 2: The return code of a run that TELEMAC-2D stopped on its limits (axqua.solvers.telemac.sortie.LIMIT_STOP). TELEMAC’s own plante.F uses 2 for a « controlled » stop on an error, which is what this is.

axqua.workflow.LIMIT_STOP_REMEDY = 'A value of that size is a numerical instability, not a flow. Look at the mesh, the bed and the initial water depth at that position. Common causes are a sink or a liquid boundary on nearly dry cells, an initial water surface far from the steady one, and a time step that is too large (hydrodynamics.desired_courant).': What to do about it, in the words every caller can pass on.

axqua.workflow.mesh_from_geometry(cfg)[source]

Rebuild a Mesh from the built geometry.slf.

Enough of one for the geometry-only helpers (water table, node masks, areas): coordinates, element table, bed and the boundary numbering. Saves re-meshing just to ask a question about a finished run.

Paramètres:: cfg (Config)

axqua.workflow.water_table_mask(cfg)[source]

Depth the porous body’s water table holds in place, per node (else None).

Rebuilt from the same config and the same seeded surface the build used, so the report and the model agree on which water is groundwater-fed rather than stray. Returns None - never raises - when the case has no water table or it cannot be reconstructed: this only decorates a report.

Paramètres:: cfg (Config)

axqua.workflow.report_wetting(cfg)[source]

Wetted-extent + outlet-profile report for a finished run.

A balanced flux budget says nothing about where the water is, which is the question this answers: how much of the wetted area actually carries flow, how much is stagnant film, how much the initial condition put there, and whether the film is still draining or has plateaued (a 2D model has neither infiltration nor evaporation, so water perched above the converged surface never leaves). The outlet profile then says whether the prescribed downstream stage is holding water up over ground that should be dry.

Writes wetting-report.csv and outlet-profile.csv into model_dir and returns report lines. Never raises: a diagnostic must not fail a successful run.

Paramètres:: cfg (Config)
Type renvoyé:: list[str]

axqua.workflow.report_sections(cfg, out_name='baffle-XS-q.csv')[source]

Discharge across the geodata.control_sections lines of a finished run.

Integrates Q = int (H*U) . n ds from the result, so the sections can be drawn and changed in GIS without re-running the solver - which is how the split of the total discharge between the threads of a braided reach gets read off and checked against field transects. Empty list when the case defines no control sections.

Paramètres:

cfg (Config)
out_name (str)

Type renvoyé:

list[str]

Run the cheap solver first, so the expensive one starts from an informed guess.

An OpenFOAM free-surface run of a water body is expensive in a way a 2D depth-averaged run is not - and almost everything it needs to know at t = 0 is something TELEMAC already answers in minutes: where the water is, how deep it is, how fast it moves, and roughly where its surface sits. Starting interFoam without that means meshing air that will never be wet, paying for the whole filling transient, and doing both in the slowest model in the chain.

This module is the orchestration that makes the seed automatic rather than a prerequisite the user has to remember. ensure_seed() returns a path to a TELEMAC result for axqua.solvers.openfoam.hotstart.load_hotstart() to read, having either found one, produced one, or been told not to.

Three ways it can get there, in order of preference

An existing converged result. simulation/r2d.slf from the real 2D study is a better seed than anything this module would generate, and it is already paid for.
A dedicated coarse pre-run. A copy of the case at pre_run.size_scale times the cell size, pre-wetted and marched at a higher Courant number, into its own folder. Minutes, not hours, and it exists so that a case which has never been through the 2D study can still go straight to OpenFOAM.
Nothing, when the user unchecks pre_run.enabled. The caller then builds cold under a flat lid, exactly as before this module existed.

Why it lives here and not in the OpenFOAM backend

tests/test_capabilities.py::test_openfoam_does_not_import_the_telemac_backend enforces that the two backends are siblings: OpenFOAM is hotstarted from a TELEMAC result, but it reads that through the shared SERAFIN codec in axqua.core.selafin, never by reaching into the other backend. Orchestration that must drive both therefore belongs above both, next to axqua.workflow - which is where it is.

The seed is an approximation, and is treated as one

TELEMAC is a model too, and it can be wrong. Nothing here freezes the 3D free surface onto the 2D answer: the surface is still solved, the lid stands a freeboard above it with room to rise, and the footprint is dilated past the wetted edge. axqua.solvers.openfoam.report.surface_freedom() checks afterwards whether the run ever needed more room than it was given. (The one exception is openfoam.mode: rigid-lid, where the surface really is prescribed - which is the trade that mode exists to make, and it says so.)

class axqua.prerun.SeedResult(path=None, source='none', converged=None, imbalance=None, runtime_s=0.0, notes=<factory>)[source]

Bases : object

The 2D (or 3D) state an OpenFOAM case will be seeded from.

Paramètres:

path (Path | None)
source (str)
converged (bool | None)
imbalance (float | None)
runtime_s (float)
notes (list[str])

path: Path | None = None

source: str = 'none'

converged: bool | None = None

imbalance: float | None = None

runtime_s: float = 0.0

notes: list[str]

property ok: bool

summary()[source]

Printable account of what happened, for a build report.

Type renvoyé:: list[str]

axqua.prerun.ensure_seed(cfg, *, enabled=None, validate_env=True)[source]

Find or produce the TELEMAC result an OpenFOAM build should be seeded from.

Never raises for an absent or unconverged seed - a cold build is a legitimate outcome and the caller reports it - except under pre_run.require: error, where an unconverged pre-run is exactly what the user asked to be stopped for.

Paramètres:

enabled (bool, optional) – Per-invocation override of openfoam.pre_run.enabled. None follows the config; False is the « uncheck the box for this run » path used by --no-pre-run and the case scripts” module-level switch.
validate_env (bool) – Passed to axqua.pipeline.run() for the pre-run.

Type renvoyé:

SeedResult

Étude de convergence en maillage

Mesh-convergence (grid-independence) study for the 2D hydraulic case.

Runs the same steady simulation on a sequence of progressively finer meshes and monitors quantities of interest phi (water depth h, scalar velocity U) at a fixed set of probe points. Convergence is judged on the Grid Convergence Index (GCI) of the finest grid triplet - with an asymptotic-range check to decide whether the GCI is trustworthy, else on the finest successive relative change - against a tolerance (default 5%; Celik et al. 2008 / Roache: GCI ~5-10% is acceptable engineering accuracy, ~1-2% is high-precision work). This is the formal way to quantify the spatial-discretization error and demonstrate grid independence.

Notes following standard practice (Celik et al. 2008, ASME J. Fluids Eng. 130):

Mesh convergence is distinct from iterative (solver) convergence - the latter (residual reduction within one run) must be reached first or the comparison is meaningless. The runs here use TELEMAC’s variable time step so each mesh marches at its own CFL-admissible dt (refining Delta x forces a smaller dt).
Use at least three meshes with a refinement factor r >= 1.3 between grids (ratio_levels()). Closer-spaced grids push the grid-to-grid solution differences into iterative/sampling noise and degenerate the GCI denominator r**p - 1, making the observed order p and the GCI unstable.
Every level (and every candidate extension) gets the physical validity checks of axqua.mesh_validity (y+, roughness regime, dx vs. ks, turbulence model consistency) - refinement is only meaningful while the closures hold.

The study can resume from completed per-level results (each level folder carries a level.json) and can extend the ladder one finer mesh at a time after showing a runtime estimate + validity check (interactive prompt; in a non-interactive session it stops and reports instead).

The TELEMAC execution is injected (the simulate callable), so the report maths are unit-testable without the solver.

axqua.convergence.extract_at_points(slf_path, quantities, points)[source]

Read the last frame of slf_path and sample quantities at points.

Type renvoyé:: dict[str, numpy.ndarray]

class axqua.convergence.LevelResult(label, cell_size, n_elem, n_nodes, min_edge, dt, runtime_s, qoi, scale=1.0, mean_depth=None, mean_velocity=None, validity=None)[source]

Bases : object

One mesh in the sequence: its resolution, size and sampled QoI.

Paramètres:

label (str)
cell_size (float)
n_elem (int)
n_nodes (int)
min_edge (float)
dt (float | None)
runtime_s (float | None)
qoi (dict[str, numpy.ndarray])
scale (float)
mean_depth (float | None)
mean_velocity (float | None)
validity (object | None)

label: str

cell_size: float

n_elem: int

n_nodes: int

min_edge: float

dt: float | None

runtime_s: float | None

qoi: dict[str, numpy.ndarray]

scale: float = 1.0

mean_depth: float | None = None

mean_velocity: float | None = None

validity: object | None = None

repr_value(qty)[source]

Representative scalar: mean magnitude over the probes.

Paramètres:: qty (str)
Type renvoyé:: float

class axqua.convergence.ConvergenceReport(levels: 'list[LevelResult]', quantities: 'list[str]', tolerance: 'float', probes: 'np.ndarray', rel_change: 'dict[str, list[float]]'=<factory>, observed_order: 'dict[str, float | None]'=<factory>, gci_fine: 'dict[str, float | None]'=<factory>, converged: 'bool' = False, case: 'str' = '', order_used: 'dict[str, float | None]'=<factory>, gci_med: 'dict[str, float | None]'=<factory>, asymptotic_ratio: 'dict[str, float | None]'=<factory>, verdict_basis: 'str' = 'rel_change')[source]

Bases : object

Paramètres:

levels (list[LevelResult])
quantities (list[str])
tolerance (float)
probes (numpy.ndarray)
rel_change (dict[str, list[float]])
observed_order (dict[str, float | None])
gci_fine (dict[str, float | None])
converged (bool)
case (str)
order_used (dict[str, float | None])
gci_med (dict[str, float | None])
asymptotic_ratio (dict[str, float | None])
verdict_basis (str)

levels: list[LevelResult]

quantities: list[str]

tolerance: float

probes: numpy.ndarray

rel_change: dict[str, list[float]]

observed_order: dict[str, float | None]

gci_fine: dict[str, float | None]

converged: bool = False

case: str = ''

order_used: dict[str, float | None]

gci_med: dict[str, float | None]

asymptotic_ratio: dict[str, float | None]

verdict_basis: str = 'rel_change'

format()[source]

Type renvoyé:: str

save(path)[source]

Type renvoyé:: Path

recommendation()[source]

Recommend the coarsest grid-independent cell size (convergence vs. cost).

A mesh is adequate when refining it further (to the next finer mesh) changes every quantity of interest by less than the tolerance; the coarsest such mesh is the cheapest converged choice. Returns a dict with the recommended LevelResult, its cell size, whether it converged, a one-line reason, and the runtime speed-up versus the finest mesh.

Type renvoyé:: dict

to_xlsx(path)[source]

Write a styled .xlsx convergence report with the cell-size recommendation.

Type renvoyé:: Path

axqua.convergence.write_readme(base_dir, *, report=None, case='', tolerance=None, quantities=None, n_probes=None, turbulence=None, extra_entries=None)[source]

Write a README.md documenting the study folder for external readers.

Explains that mesh-convergence.xlsx is the central summary file and what it contains, the governing equations and quantities examined, and the purpose of every file in each per-level model folder. The text is deliberately software-agnostic (it names TELEMAC-2D, not the build tooling).

Normally called with the finished report at the end of a study; with report=None the per-level folders are scanned instead (level.json), so a README can be regenerated for an already-completed study. extra_entries maps additional file/folder names to one-line descriptions appended to the directory-contents section.

Paramètres:

report (ConvergenceReport | None)
case (str)
tolerance (float | None)
n_probes (int | None)
turbulence (str | None)
extra_entries (dict[str, str] | None)

Type renvoyé:

axqua.convergence.build_report(levels, quantities, tolerance, probes)[source]

Assemble a ConvergenceReport (relative change, order, GCI, verdict).

The verdict is GCI-based when, for every quantity, the finest grid triplet yields a GCI whose asymptotic-range check passes (GCI(med) / (r**p GCI(fine)) within ASYMPTOTIC_BAND, ~1 in the asymptotic range): converged iff GCI(fine) < tolerance. Otherwise it falls back to the finest successive relative change vs. the tolerance (recorded in verdict_basis).

Paramètres:

levels (list[LevelResult])
tolerance (float)
probes (numpy.ndarray)

Type renvoyé:

ConvergenceReport

axqua.convergence.default_levels(cfg)[source]

Three meshes spanning one doubling of cell size around the config sizes.

Returns (label, channel_size, floodplain_size) coarse -> fine. The finest matches the config; coarser ones double the cell size (so coarse/fine = 2).

Paramètres:: cfg (Config)
Type renvoyé:: list[tuple[str, float, float]]

axqua.convergence.percent_levels(cfg, percents=(0.4, 0.2, 0.0, -0.2, -0.4))[source]

Cell-size levels at fractional offsets from the config size, coarse -> fine.

Positive percents coarsen (larger cells), negative refine (smaller cells); the default gives two 40%/20%-coarser, the baseline, and two 20%/40%-finer meshes. Returns (label, channel_size, floodplain_size).

Note

prefer ratio_levels() - the +-20% steps give successive grid ratios of only ~1.17-1.33, below the r >= 1.3 that Celik et al. (2008) recommend for a stable observed order / GCI.

Paramètres:: cfg (Config)
Type renvoyé:: list[tuple[str, float, float]]

axqua.convergence.ratio_levels(cfg, ratio=1.3, n_coarser=1, n_finer=2)[source]

Cell-size ladder with a constant refinement factor ratio, coarse -> fine.

The default gives four meshes: one coarser (x ratio), the config baseline, and two finer (/ ratio, / ratio**2) - the finest three form the GCI triplet. Celik et al. (2008) recommend ratio >= 1.3: with closer-spaced grids the solution differences drop into iterative/sampling noise and the GCI denominator r**p - 1 degenerates, so p and the GCI become unstable. Returns (label, channel_size, floodplain_size) tuples; extend the ladder one finer level at a time via run_mesh_convergence(extend_ratio=...).

Paramètres:

cfg (Config)
ratio (float)
n_coarser (int)
n_finer (int)

Type renvoyé:

list[tuple[str, float, float]]

axqua.convergence.default_probes(cfg, n=40)[source]

Probe points for the QoI: the ground-truth points if available, else samples along the channel centerline (falling back to the ROI bbox diagonal).

Paramètres:

cfg (Config)
n (int)

Type renvoyé:

numpy.ndarray

axqua.convergence.make_telemac_simulator(cfg, discharge, *, base_dir, runtime=None, n_processors=None)[source]

Build a simulate(label, ch, fp, probes, quantities) -> LevelResult that builds the case at the given resolution, runs TELEMAC once at constant discharge (variable time step for per-mesh CFL), and samples the QoI.

The level’s (ch, fp) sizes are interpreted relative to the config baseline: the level copy is built with mesh.size_scale = ch / cfg.mesh.channel_size so the whole sizing field scales - including any per-zone Max Edge Length (m) values from the mesh-zones gpkg, which would otherwise silently override the per-level sizes and leave every « level » with the same mesh (the bug behind the invalid first ering study).

Paramètres:

cfg (Config)
discharge (float)
base_dir (Path)
n_processors (int | None)

axqua.convergence.estimate_next_runtime(levels, next_cell_size)[source]

Estimated wall-clock [s] of a run at next_cell_size, with its basis.

Fits log(runtime) = a + b log(cell_size) over the completed levels; when fewer than two distinct sizes carry runtimes, or the fitted exponent is implausible, falls back to the theoretical t ~ dx**-3 scaling from the finest level (elements ~ dx**-2, CFL-bound steps ~ dx**-1). (None, ...) when no runtimes were recorded (e.g. an injected test simulator).

Paramètres:

levels (list[LevelResult])
next_cell_size (float)

Type renvoyé:

tuple[float | None, str]

axqua.convergence.run_mesh_convergence(cfg, *, discharge, levels=None, quantities=('WATER DEPTH', 'SCALAR VELOCITY'), probes=None, tolerance=0.05, simulate=None, base_dir=None, runtime=None, n_processors=None, extend_ratio=None, max_extra_levels=3, auto_extend=False, ask=None, on_level=None, result_name=None, check_validity=True)[source]

Run the convergence study and return the ConvergenceReport.

on_level(done, total, label) is called before the first mesh and after every mesh that has been run or reused, so that a job can say « mesh 2 of 4 » while the study runs. A study took twenty minutes and reported nothing until it had ended.

levels is a list of (label, channel_size, floodplain_size) coarse->fine (default: one doubling around the config sizes; prefer ratio_levels()). The sizes are interpreted relative to the config baseline - each level is built with mesh.size_scale = channel_size / cfg.mesh.channel_size so gpkg per-zone sizes scale along (see make_telemac_simulator()). simulate overrides the TELEMAC runner (used in tests); by default each mesh is built and run once at constant discharge. probes default to the ground-truth / centerline points. tolerance is the GCI / relative-change goal (default 5%, per Celik et al. 2008).

Resume: completed levels found under base_dir (result SELAFIN + level.json with matching sizes) are offered for reuse - QoI re-extracted, only missing levels run. Extension: with extend_ratio set, a not-converged study offers up to max_extra_levels additional refinements, each preceded by a runtime estimate and the mesh-validity check of the candidate size. Both go through ask(prompt, default=…) -> bool (default: stdin prompt; non-interactive sessions take the stated default: resume = yes, extend = no). An interactive prompt left unanswered for ``PROMPT_TIMEOUT_S`` seconds assumes “yes”, so an attended-then-abandoned run keeps refining rather than stalling. A candidate whose turbulence/roughness model no longer matches the pinned closure is still run (the caveat is warned, not enforced as a stop). Inject a callable for scripted runs/tests.

Auto-refinement: with auto_extend set, resume and every extension are auto-approved (no prompt, interactive or not), so the study keeps refining one grid at a time until it reaches the GCI/relative-change goal, exhausts max_extra_levels, or a level fails to mesh/run (the practical refinement limit) - then it writes the report from the completed levels.

result_name and check_validity serve a study of another code (the OpenFOAM free-surface model, axqua.solvers.openfoam.convergence): the result file of a level, and whether the checks of the TELEMAC turbulence and roughness closure (axqua.mesh_validity) apply to its levels at all.

Paramètres:

cfg (Config)
discharge (float)
tolerance (float)
base_dir (Path | None)
n_processors (int | None)
extend_ratio (float | None)
max_extra_levels (int)
auto_extend (bool)
result_name (str | None)
check_validity (bool)

Type renvoyé:

ConvergenceReport

axqua.convergence.level_progress(ctx)[source]: What a convergence study calls after each of its runs; None without a job.

axqua.convergence.write_study_report(report, folder, stem, ctx, *, readme=False)[source]

Write the report of a convergence study next to its levels, and record it.

The case scripts have always done this after the study returned. The job did not: it ran the study for twenty minutes and left the verdict in its log, so the plugin had nothing to show for it and « the report » the documentation points at did not exist. A workbook that cannot be written must not fail a study that ran. Shared by the backends: a study of each code ends the same way.

Paramètres:

folder (Path)
stem (str)
readme (bool)

Type renvoyé:

None

Physical validity checks for a mesh resolution (y+, roughness, turbulence).

Standard companion checks for the mesh-convergence study: grid refinement is only meaningful while the turbulence closure and the bed-roughness parameterization remain applicable at the finer cell size, so every level (and every candidate refinement offered to the user) gets:

the shear velocity from the fully-rough log law, u* = kappa * U / ln(11 h / ks), built from that level’s mean probe depth h, mean probe velocity U and the channel Nikuradse roughness ks;
the dimensionless wall distance y+ = u* dx / nu of the lateral wall functions (first grid point ~ one channel cell off the bank); the log-law window needs y+ >= ~30. In a river model y+ is O(1e4), so this passes for any realistic dx - it is reported as standard practice, not as the binding constraint;
the roughness Reynolds number ks+ = u* ks / nu: >= 70 fully rough (the Nikuradse friction law’s regime), 5..70 transitional (law marginal), < 5 hydraulically smooth;
the cell size vs. ks ratio: once dx < ks the mesh resolves bed scales the roughness closure already parameterizes (double-counting risk) - usually the first check to fire under refinement;
the turbulence-model consistency: what axqua.steering.turbulence_pick_for_dx() would auto-select at this dx versus the model the study is pinned to - a regime change means the pinned closure’s validity assumptions no longer hold at this resolution.

Pure maths - no solver, no gmsh; unit-testable standalone.

axqua.mesh_validity.shear_velocity_loglaw(depth, velocity, ks, kappa=0.41)[source]

Shear velocity u* [m/s] from the depth-averaged fully-rough log law.

Inverts U/u* = ln(11 h / ks) / kappa (log law integrated over the depth, zero-velocity height z0 = ks/30 -> the classic 11 h / ks argument). NaN when the inputs are unusable (h, U or ks non-positive, or 11h/ks <= 1, i.e. roughness height of the order of the flow depth).

Paramètres:

depth (float)
velocity (float)
ks (float)
kappa (float)

Type renvoyé:

axqua.mesh_validity.wall_y_plus(u_star, dx, nu=1e-06)[source]

Dimensionless wall distance y+ = u* * dx / nu of the first grid point (one channel cell off a lateral wall).

Paramètres:

u_star (float)
dx (float)
nu (float)

Type renvoyé:

axqua.mesh_validity.roughness_reynolds(u_star, ks, nu=1e-06)[source]

Roughness Reynolds number ks+ = u* * ks / nu.

Paramètres:

u_star (float)
ks (float)
nu (float)

Type renvoyé:

VerticalConvergenceReport

axqua.mesh_validity.manning_to_ks(n)[source]

Nikuradse ks [m] from a Manning n via the Strickler relation Kst = 1/n = 26 / ks^(1/6), i.e. ks = (26 n)**6.

Paramètres:: n (float)
Type renvoyé:: float

axqua.mesh_validity.channel_ks(cfg)[source]

The channel-bed Nikuradse roughness ks [m] from the case config.

Resolution order mirrors axqua.steering._friction_rows(): explicit friction.zones (a zone named *channel*/*riverbed*) > geodata.roughness_zones + roughness_table (the Zone ID overlapping the channel mesh-zone union the most) > None (checks needing ks are skipped). Manning/Strickler coefficients are converted via the Strickler relation.

Paramètres:: cfg (Config)
Type renvoyé:: float | None

class axqua.mesh_validity.MeshValidity(dx, depth, velocity, ks, u_star=nan, y_plus=nan, ks_plus=nan, dx_over_ks=None, y_plus_ok=True, ks_regime='unknown', dx_below_ks=False, turbulence_pick=None, turbulence_pick_name='', pinned_model=None, regime_change=False, estimated=False, warnings=<factory>)[source]

Bases : object

Validity of the turbulence + roughness modeling at one cell size.

Paramètres:

dx (float)
depth (float)
velocity (float)
ks (float | None)
u_star (float)
y_plus (float)
ks_plus (float)
dx_over_ks (float | None)
y_plus_ok (bool)
ks_regime (str)
dx_below_ks (bool)
turbulence_pick (int | None)
turbulence_pick_name (str)
pinned_model (int | None)
regime_change (bool)
estimated (bool)
warnings (list[str])

dx: float

depth: float

velocity: float

ks: float | None

u_star: float = nan

y_plus: float = nan

ks_plus: float = nan

dx_over_ks: float | None = None

y_plus_ok: bool = True

ks_regime: str = 'unknown'

dx_below_ks: bool = False

turbulence_pick: int | None = None

turbulence_pick_name: str = ''

pinned_model: int | None = None

regime_change: bool = False

estimated: bool = False

warnings: list[str]

lines()[source]

Human-readable summary lines (report block / extension prompt).

Type renvoyé:: list[str]

axqua.mesh_validity.check_level(cfg, *, dx, depth, velocity, ks=None, pinned_model=None, estimated=False)[source]

Run the validity checks for one cell size dx (see the module docstring).

depth/velocity are the level’s mean probe values (or the finest completed level’s, for a candidate refinement; then set estimated=True when they are placeholders). ks defaults to channel_ks(); pinned_model is the turbulence model the study is pinned to (None skips the consistency check). The turbulence auto-pick deliberately ignores any explicit hydrodynamics.turbulence_model (the study pins that on each level copy).

Paramètres:

cfg (Config)
dx (float)
depth (float)
velocity (float)
ks (float | None)
pinned_model (int | None)
estimated (bool)

Type renvoyé:

MeshValidity

Etude de la verticale couches

Vertical-layer convergence study for the TELEMAC-3D case.

The 2D study (axqua.convergence) varies the horizontal cell size; this one varies the number of sigma layers (NUMBER OF HORIZONTAL LEVELS) on the same horizontal mesh, to demonstrate that the depth-resolved solution is independent of the vertical discretization. For a sequence of layer counts (coarse = few layers -> fine = many) it runs the hotstarted non-hydrostatic 3D case (axqua.threed.build_3d_cas()), samples the depth-averaged quantities of interest (water depth, scalar velocity, from the 3D run’s 2D RESULT FILE) at the ground-truth probe points, and reports the relative change between successive layer counts plus an observed order of convergence and a Grid Convergence Index.

The « grid size » for the GCI is the layer thickness dz (which halves as the layer count roughly doubles), so the same Richardson/GCI maths as the 2D study apply - the report helpers are reused from axqua.convergence. The TELEMAC execution is injected (the simulate callable), so the report maths are unit-testable without the solver.

class axqua.vertical_convergence.VerticalLevel(n_levels, dz, n_nodes3d, n_elem3d, time_step, runtime_s, qoi)[source]

Bases : object

One vertical resolution: its layer count, thickness and sampled QoI.

Paramètres:

n_levels (int)
dz (float)
n_nodes3d (int)
n_elem3d (int)
time_step (float | None)
runtime_s (float | None)
qoi (dict[str, numpy.ndarray])

n_levels: int

dz: float

n_nodes3d: int

n_elem3d: int

time_step: float | None

runtime_s: float | None

qoi: dict[str, numpy.ndarray]

property cell_size: float

the layer thickness.

Type:: The grid size used for the GCI maths

property label: str

repr_value(qty)[source]

Paramètres:: qty (str)
Type renvoyé:: float

class axqua.vertical_convergence.VerticalConvergenceReport(levels: 'list[VerticalLevel]', quantities: 'list[str]', tolerance: 'float', probes: 'np.ndarray', rel_change: 'dict[str, list[float]]'=<factory>, observed_order: 'dict[str, float | None]'=<factory>, gci_fine: 'dict[str, float | None]'=<factory>, converged: 'bool' = False, case: 'str' = '')[source]

Bases : object

Paramètres:

levels (list[VerticalLevel])
quantities (list[str])
tolerance (float)
probes (numpy.ndarray)
rel_change (dict[str, list[float]])
observed_order (dict[str, float | None])
gci_fine (dict[str, float | None])
converged (bool)
case (str)

levels: list[VerticalLevel]

quantities: list[str]

tolerance: float

probes: numpy.ndarray

rel_change: dict[str, list[float]]

observed_order: dict[str, float | None]

gci_fine: dict[str, float | None]

converged: bool = False

case: str = ''

format()[source]

Type renvoyé:: str

save(path)[source]

Type renvoyé:: Path

recommendation()[source]

Recommend the fewest layers that are grid-independent (cheapest 3D run).

A vertical resolution is adequate when adding more layers changes every quantity of interest by less than the tolerance; the coarsest such level is the cheapest converged choice.

Type renvoyé:: dict

to_xlsx(path)[source]

Write a styled .xlsx vertical-convergence report with the recommendation.

Type renvoyé:: Path

axqua.vertical_convergence.layer_levels(cfg, data, counts=None)[source]

Layer counts to test, ascending (few -> many).

With explicit counts they are used as-is; otherwise a ladder is derived from the inferred baseline so the layer thickness roughly halves each step (a refinement ratio ~2 for the GCI): ~half, baseline, ~double and ~triple the baseline number of intervals.

Paramètres:

cfg (Config)
data (dict)

Type renvoyé:

list[int]

axqua.vertical_convergence.make_telemac3d_simulator(cfg, *, results_2d, base_dir, runtime=None, n_processors=None, total_time_factor=4.0, hotstart='constant_depth', n_time_steps=None, target_time=None, min_depth=None)[source]

Build a simulate(n_levels, probes, quantities) -> VerticalLevel.

Each layer count runs in its own base_dir/L<n>/ folder (the fixed geometry and boundary files are symlinked in, so the horizontal mesh is not rebuilt), launches telemac3d.py once and samples the depth-averaged QoI from the run’s 2D result.

target_time (s), when set, holds the simulated physical time constant across all layer counts: each level’s NUMBER OF TIME STEPS is scaled to round(target_time / dt_level) (dt shrinks with the layer count for a fixed Courant, so a finer grid takes proportionally more steps). This removes the fixed-step-count confound where finer levels reach a much earlier transient state (and so appear « not converged » for reasons of unequal spin-up, not resolution). It overrides n_time_steps.

Paramètres:

cfg (Config)
results_2d (Path)
base_dir (Path)
n_processors (int | None)
total_time_factor (float)
hotstart (str)
n_time_steps (int | None)
target_time (float | None)
min_depth (float | None)

axqua.vertical_convergence.run_vertical_convergence(cfg, *, results_2d=None, counts=None, quantities=('WATER DEPTH', 'SCALAR VELOCITY'), probes=None, tolerance=0.02, simulate=None, base_dir=None, runtime=None, n_processors=None, total_time_factor=4.0, hotstart='constant_depth', n_time_steps=None, target_time=None, min_depth=None, on_level=None)[source]

Run the vertical-layer convergence study and return the report.

on_level(done, total, label) is called before the first run and after each, so that a job can report which layer count is running.

Needs the converged 2D result (initial_run output) for the hotstart, the horizontal mesh and the probe points. counts overrides the auto-derived layer ladder; simulate overrides the TELEMAC runner (used in tests).

target_time (s) holds the simulated physical time constant across layer counts (steps scaled per level’s dt), removing the fixed-step-count spin-up confound; it overrides n_time_steps.

Paramètres:

cfg (Config)
results_2d (str | Path | None)
tolerance (float)
base_dir (Path | None)
n_processors (int | None)
total_time_factor (float)
hotstart (str)
n_time_steps (int | None)
target_time (float | None)
min_depth (float | None)

Type renvoyé:

Calage

Stage 5 - calibration points CSV and HydroBayesCal config emit.

Turns the hydraulic measurements into the calibration-points CSV that HydroBayesCal reads (id, x, y, z, <QTY>_DATA, <QTY>_ERROR columns) and emits a config_Telemac.py wiring the produced case to the calibration parameters and BAL settings declared in the axqua config.

axqua.calibration.build_calibration_csv(cfg, *, floors=None, path=None, z_resolver=None, category=None)[source]

Write the HydroBayesCal calibration-points CSV from the tidy ground truth.

The tidy table is compiled from ground_truth.sources when given, otherwise read from a user-authored ground_truth.measurements. Returns None if neither is configured.

floors clamps the per-quantity _ERROR column from below. This is a correctness guard, not a nicety: HydroBayesCal builds each observation’s variance from this column, so a measured error that is zero (or a value near zero multiplied by the relative fraction) gives that point a near-zero variance and lets the least trustworthy measurement dominate the whole likelihood. The default None leaves the existing behavior exactly as it was.

path overrides the output location, for a second CSV alongside the default one (the OpenFOAM calibration targets the same points with different columns).

z_resolver replaces the z column. The default (None) writes the tidy table’s own z, which is the surveyed bed - fine for a 2D calibration, where z is ignored, and wrong for a 3D one, where it places the extraction point on the bed and couples it to the survey’s vertical accuracy. A solver adapter supplies a resolver that places targets in the model’s own column instead (see axqua.model_column). It is a callback rather than a flag because the two HydroBayesCal bindings disagree on what z means - OpenFOAM wants an absolute elevation, TELEMAC-3D a height above the model bed - and that knowledge belongs to the adapter, not here.

category selects one tidy tab by name instead of letting the quantities decide. This is what lets a 2D and a 3D calibration read the same survey under different profile rules - the 2D one depth-averaged, the 3D one per-reading - by compiling them as separate categories (hydraulics and hydraulics-3d). They must not share a category: compile_ground_truth concatenates sources that do, which would silently hand both calibrations the union of the two row sets.

Paramètres:

cfg (Config)
floors (Mapping[str, float] | None)
path (Path | None)
z_resolver (Callable[[pandas.DataFrame], numpy.ndarray] | None)
category (str | None)

Type renvoyé:

Path | None

axqua.calibration.compile_ground_truth(cfg)[source]

Compile configured raw ground-truth sources into the tidy table (if any).

Paramètres:: cfg (Config)
Type renvoyé:: Path | None

axqua.calibration.roughness_zone_parameters(cfg)[source]

zone<N> calibration parameters declared by the roughness table.

A zone is a calibration parameter when it has a non-degenerate [ks_min, ks_max] prior and is not flagged calibration = False. Writing a genuine range is itself the declaration, so a table with bounds but no calibration column calibrates all of them rather than silently none; the column is how you opt a zone out. Excluded zones are held at their nominal ks - they still get a .tbl row and still influence the flow, they are just not inferred.

Returns an empty list for the legacy single-ks schema, which carries no bounds; there the config’s calibration.parameters remains the only source.

Paramètres:: cfg (Config)
Type renvoyé:: list

axqua.calibration.merged_parameters(cfg)[source]

Calibration parameters, merged from the three places they can be declared.

Precedence, later wins on a name collision: config calibration.parameters < the roughness table’s zone<N> rows (geodata.roughness_table with the bounds schema) < the parameters tab of the filled calibration-target template. The roughness table outranks the config because it is where the zonation itself is defined - adding a zone there must not require editing the parameter list in two files - while the spreadsheet stays the live override.

Paramètres:: cfg (Config)
Type renvoyé:: list

axqua.calibration.telemac_parameters(cfg)[source]

The declared parameters minus the ones that belong to another solver.

A case that calibrates both codes declares both sets in one calibration.parameters list, so this filter is the mirror image of axqua.solvers.openfoam.calibration.openfoam_parameters(). Without it an OpenFOAM ks / Cmu would be emitted into config_Telemac.py as though it were a TELEMAC keyword, and HydroBayesCal would spend the whole campaign rewriting a .cas line that does not exist.

Paramètres:: cfg (Config)
Type renvoyé:: list

axqua.calibration.emit_hbc_config(cfg, calibration_csv)[source]

Emit a HydroBayesCal config_Telemac.py for the produced case.

Paramètres:

cfg (Config)
calibration_csv (Path | None)

Type renvoyé:

HydroBayesCal integration: build inputs, emit config, launch calibration.

Keeps the per-case run_Bayes_cal.py / run_Bayes_cal_multiflow.py scripts thin - they only declare case-specific choices (calibration target, and for the multi-flow case the list of FlowSpec) and call run_single_flow_calibration() / run_multiflow_calibration().

Two calibration modes:

single-flow - one steady discharge, ground truth compiled from the configured ground_truth.sources (see axqua.ground_truth); the case’s built .cas is calibrated directly with HydroBayesCal’s stock bal_telemac.py.
multi-flow - several steady discharges, each with its own field campaign (axqua.campaigns) and its own steering file derived from the built base case; run with the additive bal_telemac_multiflow.py + MultiflowTelemacModel. One shared roughness is calibrated against all campaigns jointly.

HydroBayesCal is a pip dependency (pip install 'axqua[calibration]'), not an external checkout: the drivers ship with the package from 1.4.2 on (hydroBayesCal.copy_driver), so there is no directory to point at and no second conda environment to name. It is an optional extra because its surrogate stack - bayesvalidrox, gpytorch, scikit-learn - is heavy and irrelevant to building or running a TELEMAC case, so require_hbc() imports it lazily and explains the install if it is missing.

A staged driver is still run as a subprocess, but in this interpreter’s own environment: the driver is a script with an argparse main(), and it must run with TELEMAC sourced (every surrogate iteration launches the solver), which mutates the environment in ways not to inflict on the caller’s process. Pass checkout= to develop against an unreleased driver from a source tree.

Lessons baked in (see the module functions):

the built .cas must output SCALAR VELOCITY (graphic printout M);
the staged driver extracts the last (converged) SELAFIN frame, not the mean_last window that would average a dry-start transient;
HydroBayesCal’s prior-sample count drives a per-location dense covariance in gpytorch, so it is kept modest (calibration.prior_samples, default 5000) - ample for a low-dimensional roughness posterior and safe on a 16 GB box;
per-flow steering files differ only in Q, the outflow stage (from the synthesized rating at that Q), DURATION and the results name.

axqua.bayescal.ensure_graphic_output(cas_path, code='M')[source]

Ensure the .cas writes a graphic-printout variable (default M = SCALAR VELOCITY). Returns True if the file was patched. HydroBayesCal reads the quantity straight from the results SELAFIN, so it must be printed.

Paramètres:

cas_path (Path)
code (str)

Type renvoyé:

bool

axqua.bayescal.other_calibration_running(model_dir)[source]

A TELEMAC run from this model dir already active (would fight over the shared friction.tbl).

Paramètres:: model_dir (Path)
Type renvoyé:: bool

axqua.bayescal.launch(cfg, driver, config_path, *, env=None, note='HydroBayesCal calibration')[source]

Run a staged TELEMAC driver with TELEMAC sourced. See axqua.hbc.launch_driver().

env is accepted and ignored; it named the separate conda environment this used to need, before HydroBayesCal became a dependency of axqua itself.

Paramètres:

cfg (Config)
driver (Path)
config_path (Path)
env (str | None)
note (str)

Type renvoyé:

axqua.bayescal.build_velocity_csv(cfg, *, vel_err_floor=0.01, depth_err_floor=0.02)[source]

Compile the configured ground truth and write the calibration-points CSV.

The velocity target is the horizontal FlowTracker speed (0.6-depth proxy for the depth-averaged velocity) with propagated, floored error; water depth is carried alongside. Reads ground_truth.sources via axqua.ground_truth.compile_ground_truth().

Paramètres:

cfg (Config)
vel_err_floor (float)
depth_err_floor (float)

Type renvoyé:

tuple[Path, pandas.DataFrame]

axqua.bayescal.run_single_flow_calibration(cfg, *, calibration_quantities=None, extraction_quantities=None, vel_err_floor=0.01, depth_err_floor=0.02, prepare_only=False, checkout=None, env=None)[source]

End-to-end single-discharge calibration of the built case.

Compiles the calibration CSV, ensures the .cas prints the target, emits the HydroBayesCal config, stages the driver and (unless prepare_only) launches it. Returns the driver exit code (0 when prepare_only).

Paramètres:

cfg (Config)
vel_err_floor (float)
depth_err_floor (float)
prepare_only (bool)
checkout (Path | None)
env (str | None)

Type renvoyé:

axqua.bayescal.AS_BUILT = 'case-as-built': Folder in the calibration directory that holds the files of the built case while a calibration rewrites them.

axqua.bayescal.case_as_built(cfg)[source]

Hand the built case back the way the calibration found it.

HydroBayesCal runs TELEMAC in the folder of the built case and writes every parameter set it tests into the files there: the roughness values into the friction table, the name of the results file into the steering file. When it has finished, the case holds the last set it tried, which is neither the case that was built nor the calibrated one, and the next steady run uses it without a word. On the Isar example the friction table read ks = 0.195 m in zone 4 after a calibration of a case built with 0.05 m.

The files are copied into the calibration folder before the driver starts and copied back when it returns, whether it succeeded or not. A calibration that is killed restores nothing; see restore_as_built() for that case.

Paramètres:: cfg (Config)

axqua.bayescal.restore_as_built(cfg)[source]

Copy the files a calibration set aside back into the built case.

Returns whether there was anything to restore. A copy is only ever found here outside a running calibration when that calibration was killed, by a cancelled job or a power cut, before it could restore the case itself. The copy is then the case as built, and what is in the model folder is the last parameter set the driver had reached. Every TELEMAC run of the case calls this first, so a cancelled calibration cannot leak into the next simulation.

Paramètres:: cfg (Config)
Type renvoyé:: bool

class axqua.bayescal.FlowSpec(name, discharge, kind, values, positions=None, sheet='KB15', duration=None, vel_err_floor=0.01, hotstart_from=None)[source]

Bases : object

One steady discharge in a multi-flow calibration.

kind + values (+ positions) feed axqua.campaigns(); the steering file is derived from the built base case, differing only in Q, the outflow stage, DURATION and the results name. vel_err_floor raises the per-point velocity error for a campaign that should inform but not dominate the joint likelihood (e.g. a single cross-section).

Paramètres:

name (str)
discharge (float)
kind (str)
values (Path)
positions (Path | None)
sheet (str)
duration (float | None)
vel_err_floor (float)
hotstart_from (str | None)

name: str

discharge: float

kind: str

values: Path

positions: Path | None = None

sheet: str = 'KB15'

duration: float | None = None

vel_err_floor: float = 0.01

hotstart_from: str | None = None

compile(crs_epsg)[source]

Paramètres:: crs_epsg (int)
Type renvoyé:: pandas.DataFrame

axqua.bayescal.outflow_stage(cfg, discharge, out_dir)[source]

Outflow water-surface elevation at discharge from the synthetic normal-flow rating (extrapolation warning: unreliable far above the geometry calibration discharge / overbank).

Paramètres:

cfg (Config)
discharge (float)
out_dir (Path)

Type renvoyé:

axqua.bayescal.write_flow_cas(cfg, base_cas, flow, rating_dir, *, duration=None, dest_dir=None, listing=None, graphic=None)[source]

Derive one flow’s steering file from the built base .cas.

With flow.hotstart_from the run continues from that result file instead of the base case’s pre-wet/dry seed. DURATION then measures re-equilibration after the roughness change, not the fill - but it must still be long enough for the field to forget the seed, or every run is pulled toward the roughness the seed was converged at and the calibration under-reports sensitivity. Verify it at the prior extremes before trusting a short hotstart duration.

Paramètres:

cfg (Config)
base_cas (Path)
flow (FlowSpec)
rating_dir (Path)
duration (float | None)
dest_dir (Path | None)
listing (int | None)
graphic (int | None)

Type renvoyé:

axqua.bayescal.emit_multiflow_config(cfg, out_dir, model_dir, flows, csv_paths, *, n_cpus, init_runs, max_runs, complete_bal_mode=True, only_bal_mode=False, prior_samples=None, adaptive_init_runs=None)[source]

Write config_Telemac_multiflow.py (standard blocks + a multiflow block of per-flow steering/CSV entries).

Paramètres:

cfg (Config)
out_dir (Path)
model_dir (Path)
flows (list[FlowSpec])
csv_paths (dict[str, Path])
n_cpus (int)
init_runs (int)
max_runs (int)
complete_bal_mode (bool)
only_bal_mode (bool)
prior_samples (int | None)
adaptive_init_runs (bool | None)

Type renvoyé:

axqua.bayescal.compile_flow_csvs(cfg, flows, multiflow_dir)[source]

Compile each flow’s calibration-points CSV; returns {flow name: path}.

Paramètres:

cfg (Config)
flows (list[FlowSpec])
multiflow_dir (Path)

Type renvoyé:

dict[str, Path]

axqua.bayescal.run_multiflow_smoke(cfg, flows, multiflow_dir, csv_paths, *, checkout=None, env=None, init_runs=3)[source]

Isolated end-to-end plumbing test: tiny 30 s runs in a copied model dir.

Verifies steering/friction updates, extraction at every point, per-run JSON accumulation (rows must differ across init_runs distinct ks levels) and the combined matrix shape - without the full solver cost.

Paramètres:

cfg (Config)
flows (list[FlowSpec])
multiflow_dir (Path)
csv_paths (dict[str, Path])
checkout (Path | None)
env (str | None)
init_runs (int)

Type renvoyé:

axqua.bayescal.run_multiflow_calibration(cfg, flows, *, launch_mode='prepare', checkout=None, env=None, force=False)[source]

Compile CSVs + per-flow steering, emit config, stage drivers, then act by launch_mode:

prepare - write everything, do not launch (default);
smoke - run the isolated plumbing test;
run - launch the full calibration (initial design + BAL);
resume - reuse completed per-flow initial designs (only_bal_mode) and go straight to surrogate + BAL.

Paramètres:

cfg (Config)
flows (list[FlowSpec])
launch_mode (str)
checkout (Path | None)
env (str | None)
force (bool)

Type renvoyé:

Multi-campaign FlowTracker -> per-flow HydroBayesCal calibration-point CSVs.

A multi-discharge calibration compares one model against velocity ground truth from several field campaigns, each measured at a different steady discharge. This module turns each campaign’s FlowTracker2 export into a calibration-points CSV in the HydroBayesCal schema (first four columns id, x, y, z read by position, then <QTY>_DATA / <QTY>_ERROR read by name).

Per vertical it keeps the measurement nearest 0.6 x depth (the standard depth-averaged-velocity proxy that TELEMAC-2D SCALAR VELOCITY = sqrt(u^2+v^2) is compared to) and forms the target from the horizontal components only. WATER DEPTH (the vertical’s total depth) is carried alongside.

Three source layouts are handled (kind on config-level flow specs, or the compile_* helpers directly):

adapter - a revised summary workbook whose sheet already has one row per vertical, joined to a DGPS point layer by ID (via axqua.ground_truth.read_flowtracker()); the standard axqua path.
transect - a taped cross-section whose Station is <vertical>-<sub> with 0.2/0.6/0.8 sub-verticals and coordinates only on bank-anchor rows; positions come from a companion point GeoPackage keyed by vertical number.
inline - verticals with EPSG coordinates repeated inline on every row and 0.2/0.6/0.8 profiles.
points - a point layer with one point per reading, as the corrected campaign layers of 2026-10 are (via axqua.ground_truth.read_points()); the readings of a vertical are reduced by a profile rule, the depth average by default.

The per-point velocity error propagates the FlowTracker component errors and is floored (vel_err_floor). Raise the floor for a campaign that is not an independent representative sample of the 2D flow field (e.g. one dense cross-section), so it informs but does not dominate the joint likelihood (HydroBayesCal weights each point by 1/variance).

axqua.campaigns.velocity_and_error(u, v, u_err, v_err, vel_err_floor=0.01)[source]

Horizontal speed sqrt(u^2+v^2) and propagated per-point error (floored).

sigma_V = sqrt((u*su)^2 + (v*sv)^2) / V, then clipped up to vel_err_floor.

axqua.campaigns.assemble_velocity_csv(x, y, z, u, v, u_err, v_err, h, labels, vel_err_floor=0.01, depth_err_floor=0.02)[source]

Build the HydroBayesCal calibration-points frame from per-vertical arrays.

Type renvoyé:: pandas.DataFrame

axqua.campaigns.compile_adapter(values_xlsx, positions, crs_epsg=25832, vel_err_floor=0.01, label='pt')[source]

Revised summary workbook joined to a DGPS layer by ID (standard path).

Paramètres:

values_xlsx (Path)
crs_epsg (int)
vel_err_floor (float)
label (str)

Type renvoyé:

pandas.DataFrame

axqua.campaigns.compile_transect(values_xlsx, positions_gpkg, sheet='KB15', vel_err_floor=0.01, target_depth=0.6, label='tr')[source]

Taped cross-section: values from the xlsx, positions from a point gpkg.

Station is <vertical>-<sub>; positions come from positions_gpkg whose Point attribute is the (integer) vertical number.

Paramètres:

values_xlsx (Path)
positions_gpkg (Path)
sheet (str)
vel_err_floor (float)
target_depth (float)
label (str)

Type renvoyé:

pandas.DataFrame

axqua.campaigns.compile_inline(values_xlsx, sheet='KB15', vel_err_floor=0.01, target_depth=0.6, label='in')[source]

Verticals with inline EPSG coordinates on every row and 0.2/0.6/0.8 profiles.

Paramètres:

values_xlsx (Path)
sheet (str)
vel_err_floor (float)
target_depth (float)
label (str)

Type renvoyé:

pandas.DataFrame

axqua.campaigns.compile_points(layer, crs_epsg, vel_err_floor=0.01, label='pt', profile='depth-average')[source]

A point layer with one point per reading -> one calibration point per vertical.

The layer carries no component errors, so every point gets vel_err_floor. It carries no elevation either, so z is 0, which the 2D calibration ignores.

Paramètres:

crs_epsg (int)
label (str)
profile (str)

Type renvoyé:

pandas.DataFrame

axqua.campaigns.compile_campaign(kind, **kwargs)[source]

Dispatch to the adapter / transect / inline / points layout compiler.

Paramètres:: kind (str)
Type renvoyé:: pandas.DataFrame

Solver-agnostic HydroBayesCal plumbing: find it, stage a driver, launch it.

The part of the calibration path that is the same whichever solver is being calibrated. The solver-specific halves live beside their solvers:

axqua.bayescal - TELEMAC (.cas rewriting, config_Telemac.py, the single- and multi-flow entry points);
axqua.solvers.openfoam.calibration - OpenFOAM (the interFoam case template, config_OpenFOAM.py).

They are genuinely separate rather than one parameterised emitter: the two HydroBayesCal config schemas differ in block names (simulation vs hydrodynamic_simulation), in block membership (n_cpus lives under sampling for OpenFOAM and at top level for TELEMAC), in carrying a whole extra interfoam block, and in what case_template_dir means - referenced in place for TELEMAC, copied per run for OpenFOAM. A single emitter would be an if solver == ladder with two disjoint bodies. What they really share is this module: locating HydroBayesCal, staging a driver out of it with the patches axqua needs, and running that driver inside the right solver environment.

axqua.hbc.require_hbc()[source]

Import HydroBayesCal, or explain how to install it.

It is an optional dependency (pip install axqua[calibration]): the surrogate stack it pulls in - bayesvalidrox, gpytorch, scikit-learn - is heavy and irrelevant to building or running a solver case, which is what most of axqua does. So it is imported where it is used rather than at module import.

axqua.hbc.hbc_version()[source]

Installed HydroBayesCal version, for the staging log.

Type renvoyé:: str

axqua.hbc.EXTRACTION_PATCH = {'output_extraction_time="mean_last"': 'output_extraction_time="last"'}: The extraction-window patch every staged driver gets. The stock drivers average the last window of result frames (mean_last); on a run marching to steady state from a dry or pre-wetted start that averages the residual transient into the calibration values. last takes the converged frame.

axqua.hbc.stage_driver(out_dir, template_name, *, checkout=None, also=(), replacements=None, required=())[source]

Copy a HydroBayesCal driver into out_dir, with axqua’s patches applied.

The driver comes from the installed HydroBayesCal package (hydroBayesCal.copy_driver, which also brings any sibling a driver imports), so there is no checkout path to configure. checkout overrides that with a source tree, for developing against an unreleased driver.

replacements are further literal-to-literal rewrites, applied on top of EXTRACTION_PATCH. required names literals that must have matched somewhere; if one did not, this raises rather than proceeding. That guard is the point of the argument: a patch rewrites a string literal in someone else’s file, so without it a HydroBayesCal release that changes the literal turns the patch into a silent no-op - and the failure then shows up as a wrong result hours later rather than as an error at staging time.

Every staged file is patched, not just the primary one. That is not caution: bal_telemac_multiflow.py imports run_complex_model / run_bal_model from its bal_telemac.py sibling and calls them without passing output_extraction_time, so a multi-flow run takes the sibling’s default. With only the primary patched, multi-flow calibrations silently averaged the transient - the exact failure this patch exists to prevent - while single-flow ones did not.

Paramètres:

out_dir (Path)
template_name (str)
checkout (Path | None)
also (tuple[str, ...])
replacements (Mapping[str, str] | None)
required (Sequence[str])

Type renvoyé:

axqua.hbc.solver_running(pattern, model_dir, *, extra=())[source]

Whether a solver process from model_dir is already active.

Two calibrations sharing one model directory fight over the files each rewrites per run (the friction table, the steering file, the field dictionaries), so this is checked before launching rather than diagnosed afterwards from a confusing result.

Paramètres:

pattern (str)
model_dir (Path)
extra (Sequence[str])

Type renvoyé:

bool

axqua.hbc.launch_driver(environment, driver, config_path, *, note='HydroBayesCal calibration', extra_args=(), env=None)[source]

Run a staged driver inside environment, in this interpreter’s Python.

HydroBayesCal is a dependency of axqua, so it is importable here - there is no second conda environment to name and no interpreter to guess. The driver is still run as a subprocess rather than imported, for two reasons that matter over a calibration lasting hours: it is a script with module-level state and an argparse main(), and it has to run with the solver sourced, since every surrogate iteration launches the solver. Sourcing mutates the environment, which is exactly the sort of thing not to do to the caller’s own process.

sys.executable is used explicitly so the subshell cannot pick up a different python from the sourced solver environment.

Returns the driver’s exit code.

Paramètres:

environment (SolverEnvironment)
driver (Path)
config_path (Path)
note (str)
extra_args (Sequence[str])
env (Mapping[str, str] | None)

Type renvoyé: