Dike breach

The dike breach model described here is implemented in the pyDike class. It provides a simplified parametric representation of the erosion and breaching of an homogeneous, non-cohesive fluvial dike or dam due to overtopping.

Note

For more details, refer to the thesis of Vincent Schmitz (2025).

It corresponds to an adaptation of DLBreach (Weiming Wu, 2013, 2016).

The model is designed to simulate the evolution of dike or dam breach over time, including the calculation of the breach discharge and water levels in the main channel/reservoir and in the floodplain.

The model can be decomposed into a hydrodynamic module (which can be replaced by a 1D or 2D hydrodynamic model, if coupled) and a breach module. The hydrodynamic module calculates the water levels and discharges in the main channel and floodplain, while the breach module simulates the erosion and widening of the breach over time.

Although physically based, the model uses a set of empirical parameters to represent the physical processes involved in dike/dam failure.

Initialization

The model is initialized by creating a pyDike object.

from wolfhece.dikeBreaching import pyDike
dike = pyDike()

This command instantiates the simulation with all default parameters defined. These can be accessed or modified by editing the attributes of the pyDike instance.

Main Parameters

The parameters are grouped in the following categories:

Test Definition

  • Test_ID : Test name.

Time Parameters

  • dt : Constant time step in seconds.

  • t_end : Total simulation time in seconds.

Save Parameters

  • exportMainResults : Boolean. Save main outputs as time series (time, inflow discharge, breach widening and deepening, breach discharge, WL, erosion-related variables).

  • extractTriangulation : Boolean. Save triangulation for visualization or interpolation on 2D matrix.

  • path_saveOutputs : Path to store simulation results.

Physical Parameters

  • g : Gravitational acceleration.

  • d50 : Median grain diameter.

  • nu : Kinematic viscosity of water.

  • rho : Water density.

  • rho_s : Sediment density.

  • p : Dike/dam porosity.

  • phi : Friction angle (in degrees).

  • suspension : Boolean for including suspended sediment load.

Geometrical Parameters

Dike Geometry

  • dam : Boolean. True if dam, False if dike.

  • Su, Sd_ini : Upstream and initial downstream slopes (H/V).

  • Lk : Crest width.

  • h_d : Dike/dam height.

  • complete_erosion : Boolean. If erosion reaches dam/dike non-erodible base. Should be False to avoid discontinuities.

  • dx_min : Minimal length of the flat top reach (prevents it from disappearing and avoid a sharp discontinuity in the breach discharge evolution).

  • xnotch_ini, ynotch_ini : Initial notch center position (m).

  • end_up, end_down : Distance between the initial notch center and the upstream/downstream extremity of the embankment. “end_up” should be negative.

  • elevation_shift : Z correction for matching 2D topo. By default, the embankment bottom is at 0 m at the initial notch center.

  • slope : Longitudinal slope of the dike/dam (V/H).

  • horiz_rotation : Horizontal rotation of the dike/dam (in degrees, positive in trigonometric direction). By default, the dike/dam is oriented along the x-axis.

  • river_bank : “left” or “right”. Defines on the which of the impoundment is theembankment located.

Breach Geometry

  • h_b_ini, b_ini : Initial breach depth and bottom width.

  • m : Side slope (at the moment, fixed to 1 / tan(phi)).

  • m_up, m_down : Upstream and downstream breach side slopes (at the moment, fixed to m).

Main Channel Geometry

  • reservoir_shape : Type of reservoir/main channel: rectangular, trapezoidal, or irregular (stage storage curve needed then).

  • pathStageStorage : Stage-storage curve file path (only required if reservoir_shape = irregular).

  • Ar : Reservoir/main channel surface area (m^2). Only used if reservoir_shape = rectangular.

  • lmc, wmc, S_lat : Reservoir/main channel length, width and side slope (opposite to the embankment). Only used if reservoir_shape = trapezoidal.

Floodplain Geometry

  • StageStorage_FP : Boolean to use stage-storage curve in floodplain.

  • pathStageStorage_FP : Corresponding path.

Flow Parameters

  • Qd : Drain discharge (m^3/s). If Qd is a path to a file, it is assumed to be a time series of drain discharges.

  • Qin : External inflow discharge (m^3/s). If Qin is a path to a file, it is assumed to be a time series of inflow discharges.

  • z_s_ini, z_t_ini : Initial reservoir/river and tailwater levels. If z_s_ini = -999, the initial water level is set to 99.9% of the dike/dam height.

  • Qin_coef : Inflow multiplier (default = 1, useful for uncertainty analysis only).

Outflow Parameters

  • Qo_module : Boolean. Use module to compute outflow (e.g. if defined by rating curve).

  • Qo : Path to outflow discharge module. Not supported yet.

Empirical Parameters (see DLBreach documentation for more details)

  • c1, c2, c_eff : Weir coefficients.

  • lambda_in, lambda_out : Head losses before and after the breach section.

  • An, An_prime : Empirical coefficients for roughness related to Manning’s coefficient.

  • n_min : Minimum value for Manning’s coefficient.

  • lbda : Adaptation length = distance needed by the flow to be fully charged with sediment. If lbda=0, instant sediment equilibrium.

  • theta_cr : Critical shields parameter.

  • Sp : Corey shape factor.

  • C_stara to C_stard : Suspended sediment parameters (empirical).

  • qb_stara, qb_starb : Bedload parameters (empirical).

  • lambda0a, lambda0b : Shear stress coefficients (empirical).

  • cb_coef : Concentration correction coefficient (empirical).

  • b_eff_frac : Effective breach width fraction (>1 = full breach width with uniform erosion / enforced to “Infinity” for dams). Warning: if =1, erosion is assumed to be applied on the D/S breach extremity only.

Parameter Management

After initiating the pyDike object, vectors should be initialized using the “run_initialization” method. Then, parameters can be exported, modified, or loaded externally. Warning : only JSON format supported. The name of the file can be arbitrary, but it will be save with the “_paramsDike.json” extension. Only files with this extension can be loaded.

from pathlib import Path
from wolfhece.dikeBreaching import pyDike

dike = pyDike("my_test")
dike.run_initialization(params_dir = Path("./parametrization"))
params = dike.get_params()
dike.save_params("my_test", Path("./parametrization"))
dike.set_params("my_test", Path("./parametrization"))

Execution

To run a simulation, provide the current time index, the time step, the current time and specify if the dike model is coupled to a hydrodynamic model or not. The method run will execute the simulation based on the initialized parameters. A loop should be implemented as the “run” method only executes one time step at a time. For a complete simulation, you can loop through the time steps as follows:

myrun = pyDike(name='my_test')
myrun.run_initialization(params_dir = Path("./parametrization"))
for time_idx in np.arange(0,myrun.t_end_idx):
    myrun.run(time_idx)

This will perform the simulation using the set parameters and optionally save the main results and triangulation output, depending on the boolean flags.

Output

The model may save the following:

  • Main output file : Evolution of time, inflow discharge, breach widening and deepening, breach discharge, WL, erosion-related variables. Text files with time series of these variables are saved in the specified path. The file name is Test_ID+”_mainOutputs.txt”.

  • Triangulation file : Stored as a dictionary in JSON format if requested. The file name is Test_ID+”_triangulation.json”.

  • Simulation parameters : As a readable JSON dictionary. The file name is Test_ID+”_paramsDike.json”.

Note

This model is designed for conceptual demonstration and should be coupled with 1D/2D models for advanced hydraulic analysis or breach propagation visualization.

Use in WOLF GUI

The pyDike model can be used in the WOLF GUI by selecting the “Add dike” or “Create dike” from the “Add…” or “Create…” menus. The parameters can be set through the GUI interface (right click on the dike object and select “properties”), and the simulation can be run directly from there (top right “Dike” menu appears after initialization of a dike object). The results will be displayed in the GUI (available in the top right “Dike” menu), and the output files will be saved in the specified directory. The breach evolution can also be visualized in 3D by selecting the “Show triangulation” option in the “Dike” menu. A windows pops up with the triangulation of the dike and the breach evolution. The triangulation can be rotated and zoomed in/out using the mouse. The triangulation corresponding to a specific time step can be saved as a .png file by clicking on the “Save frame” button in the triangulation window. This triangulation can also be added to the WOLF objects as a triangulation object by clicking on the “Add current frame to viewer” button in the triangulation window. The selected triangulation can then be exported from the WOLF GUI by right-clicking on the triangulation object and selecting “Save as”.