hydromt_sfincs.workflows.downscaling.adjust_zsmax_energyhead#

hydromt_sfincs.workflows.downscaling.adjust_zsmax_energyhead(zsmax: DataArray | UgridDataArray, qmax: DataArray | UgridDataArray, zb: DataArray | UgridDataArray | None = None, hmin: float = 0.05, q_threshold: float = 0.01) → DataArray | UgridDataArray[source]#

Add the velocity head v²/(2g) to zsmax (Bernoulli correction).

Lifts the water level on wet cells where the unit discharge exceeds q_threshold, converting zsmax to the total-energy head H = zsmax + v² / (2g). The wet-cell set is preserved: NaN cells stay NaN.

This is a method-agnostic pre-step — the returned DataArray can be consumed by any downscaling method (constant, bilinear, raw, etc.). Works on both SFINCS quadtree grids (xu.UgridDataArray) and regular grids (xr.DataArray); zsmax, qmax, and zb must all share the same grid.

Parameters:

  • zsmax (xu.UgridDataArray or xr.DataArray) – Maximum water level (m) on a SFINCS grid — quadtree (xu.UgridDataArray) or regular (xr.DataArray). NaN where dry.

  • qmax (xu.UgridDataArray or xr.DataArray) – Maximum unit discharge magnitude (m²/s), cell-centred — one value per cell, with the same shape and grid as zsmax. This is the convention SFINCS writes to sfincs_map.nc (variable qmax) when storefluxmax=1; no face-to-centre reduction is needed. The sign is ignored (|qmax| is used internally). Formula: vel_head = q² / (h² · 2g) with h = max(zsmax - zb, hmin).

  • zb (xu.UgridDataArray or xr.DataArray, optional) – Bed elevation (m) at cell centres, used to estimate depth. If omitted, a constant depth of hmin is assumed (conservative — overestimates velocity and therefore the head correction).

  • hmin (float, optional) – Minimum depth (m) for velocity estimation, by default 0.05.

  • q_threshold (float, optional) – Minimum unit discharge magnitude (m²/s) to apply the correction, by default 0.01. Cells below this threshold keep their original zsmax.

Returns:

zsmax with the velocity head added on qualifying cells. Same grid and same wet-cell set as the input. result >= zsmax on every wet cell (velocity head is always non-negative).

Return type:

xu.UgridDataArray or xr.DataArray

On this page