Dike breach ========================= The dike breach model described here is implemented in the `pyDike` class. It provides a simplified 0D representation of the erosion and breaching of a 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 a dike or dam breach over time, including the calculation of outflow discharge and water levels in the main channel/reservoir and in the floodplain. It is particularly useful for understanding the dynamics of dike failures and their potential impacts on surrounding areas. 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, including sediment transport, erosion rates, and breach geometry. Initialization -------------- The model is initialized by creating a `pyDike` object. .. code-block:: python 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 (breach, Q, WL). - **extractTriangulation** : 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). - **xnotch_ini** : Initial notch position (m). - **xmin_topo, ymin_topo** : Origin of the dike/dam. Breach Geometry *************** - **m** : Side slope (default = 1 / tan(phi)). - **m_up, m_down** : Upstream and downstream breach side slopes (default = m). - **h_b_ini, b_ini** : Initial breach depth and bottom width. Main Channel Geometry ********************** - **elevation_shift** : Z correction for matching 2D topo. - **slope** : Longitudinal slope of the dike/dam. - **reservoir_shape** : Type of reservoir/main channel: rectangular, trapezoidal, or irregular (stage storage curve needed then). - **pathStageStorage** : Stage-storage curve file path. - **Ar, lmc, wmc, S_lat** : Reservoir/main channel dimensions depending on reservoir shape. Floodplain Geometry ******************** - **StageStorage_FP** : Boolean to use stage-storage curve in floodplain. - **pathStageStorage_FP** : Corresponding path. Flow Parameters +++++++++++++++ - **Qd** : Drain discharge (m^3/s). - **Qin** : External inflow discharge (m^3/s). - **z_s_ini, z_t_ini** : Initial upstream and tailwater levels. - **Qin_coef** : Inflow multiplier (default = 1, useful for uncertainty analysis only). - **Qo_module** : Boolean. Use module to compute outflow (e.g. if defined by rating curve). - **Qo** : Outflow discharge (m^3/s). Empirical Parameters +++++++++++++++++++++ - **c1, c2, c_eff** : Weir coefficients. - **lambda_in, lambda_out, lambda_loss** : Head losses. - **An, An_prime** : Empirical coefficients for roughness related to Manning's coefficient. - **n_min** : Minimum value for Manning’s coefficient. - **lbda** : Adaptation length (Wu) = 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). Warning: if =1, erosion is assumed to be applied on the D/S breach extremity only. Should be >1 for uniform erosion, i.e., for dams. Parameter Management -------------------- After initialization, parameters can be exported, modified, or loaded externally. .. code-block:: python params = dike.get_params() dike.save_params("my_test.json", Path("./outputs")) dike.set_params("my_test.json", Path("./outputs")) Execution --------- To run a simulation: .. code-block:: python dike.run(store_dir=Path("./outputs")) 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 files** : breach width, depth, discharge evolution. - **Triangulation file** : stored as a dictionary in JSON format if requested. - **Saved parameters** : as a readable JSON dictionary. .. note:: This model is designed for conceptual demonstration and should be coupled with 1D/2D models for advanced hydraulic analysis or breach propagation visualization.