Merge pull request #398 from nens/333-explain-breach-flow

333 explain breach flow

source/h_1d2d_exchange.rst

@@ -55,45 +55,7 @@ When the calculation type is *connected*, a 1D2D connection is made for each cal
 
    Four examples of connected elements. 1) The exchange level is higher than (the lowest pixel in) the 2D cell. 2) The exchange level is lower than (the lowest pixel in) the 2D cell. 3) The exchange level is not set; flow is possible as soon as the 1D water level exceeds the level of the lowest pixel in the 2D cell. 4) Double connected channel, where exchange levels have different values.
 
-1D2D Flow
-"""""""""
-
-Flow through the 1D2D connection is computed using a reduced momentum balance:
-
-.. math::
-   :label: reduced 1D momentum equation
-
-   0 = -g\frac{\partial \zeta}{\partial s} \big\rvert_{1D2D}-\frac{\tau_f}{\rho}
-
-This momentum equation in combination with a cross-section defines the flux between the computational domains.
-
-.. math::
-   :label: Q 1D2D
-
-   Q_{1D2D} = u_{1D2D} A_{1D2D}
-
-The cross-sectional area of the 1D2D connection is the exchange depth times an exchange length. This exchange length is calculated in a different way for channels and for pipes. For pipes, the exchange length is based on the storage areas of the corresponding connection node [S]:
-
-.. math::
-   :label: storagearea
-
-   A_{1D2D} = L_{1D2D} H_{1D2D} = 4 \sqrt{S H_{1D2D}}
-
-In case of open water elements, there calculation of the exchange length is different for connected (two banks per 1D2D connection) and double connected (one bank per 1D2D connection).
-For connected elements:
-
-.. math::
-   :label: storagearea2
-
-   A_{1D2D} = L_{1D2D} H_{1D2D} = 2 L_{bank} H_{1D2D}
-
-
-For double connected elements this implies:
-
-.. math::
-   :label: storagearea3
-
-   A_{1D2D} = L_{1D2D} H_{1D2D} = L_{bank} H_{1D2D}
+How flow through 1D2D connections is calculated is described in :flow_1d2d:
 
 Customising 1D2D connections for channels
 """""""""""""""""""""""""""""""""""""""""
@@ -155,3 +117,49 @@ The embedded element modifies the storage of the 2D cell it is embedded in. The
 Cross-sectional area in embedded flowlines
 """"""""""""""""""""""""""""""""""""""""""
 The cross-sectional area that is used in the 1D flow calculation is determined in a way similar to how the storage is handled. The part of the 1D cross-section that is below the DEM pixels is used, the rest is ignored. The cross-sectional area that is used for the calculation of 2D flow is unaltered by the embedded elements that pass through the cells.
+
+
+1D2D Flow
+---------
+
+Flow through a 1D2D connection is computed using a reduced momentum balance:
+
+.. math::
+   :label: reduced 1D momentum equation
+
+   0 = -g\frac{\partial \zeta}{\partial s} \big\rvert_{1D2D}-\frac{\tau_f}{\rho}
+
+This momentum equation in combination with a cross-section defines the flux between the computational domains.
+
+.. math::
+   :label: Q 1D2D
+
+   Q_{1D2D} = u_{1D2D} A_{1D2D}
+
+The cross-sectional area of the 1D2D connection is the exchange depth times an exchange length. This exchange length is calculated in a different way for channels and for pipes. For pipes, the exchange length is based on the storage areas of the corresponding connection node [S]:
+
+.. math::
+   :label: storagearea
+
+   A_{1D2D} = L_{1D2D} H_{1D2D} = 4 \sqrt{S H_{1D2D}}
+
+In case of open water elements, there calculation of the exchange length is different for connected (two banks per 1D2D connection) and double connected (one bank per 1D2D connection).
+For connected elements:
+
+.. math::
+   :label: storagearea2
+
+   A_{1D2D} = L_{1D2D} H_{1D2D} = 2 L_{bank} H_{1D2D}
+
+
+For double connected elements this implies:
+
+.. math::
+   :label: storagearea3
+
+   A_{1D2D} = L_{1D2D} H_{1D2D} = L_{bank} H_{1D2D}
+   
+Breach flow
+-----------
+
+Breaches are a special case of 1D2D connections. The flow through a breach is calculated with the broad crested weir equation, more information on the exact calculation of breach flow can be found in :ref:`breach_flow`.

source/h_breaches.rst

@@ -1,14 +1,17 @@
 .. _breaches:
 
 Breaches
-------------
+========
 
 3Di can simulate the consequences of a breach in a levee. In such case, the dimensions of the breach determine flow through the breach and therefore the flood. The growth of a breach is a very complex process. It is a phenomenon where hydrodynamics, morphology, groundwater and soil mechanics interact. Many aspects of this interaction is still unknown, and therefore it is difficult to model. Moreover, detailed modeling would require very detailed information about the levee. Generally, there is only a limited amount of information about the soil, structure, moisture content etc of the levee.   Nevertheless, rules of thumb have been developed that describe the breach growth, which allow us to make an estimate of the breach growth.
 
 In a 3Di model, flow may occur between 1D and 2D elements. In certain cases this exchange is limited by a levee. The exchange height is determined by the height of the levee. When a few extra properties of the levee are specified for these connections, a breach can be modelled that can grow over time. More information on levees, can be found in :ref:`obstacles`
 
+If you would like to know how to build a model with breaches, follow :ref:`flood_model`.
+
+
 Breach growth formulation
-++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++
 
 In 3Di, the formula of Verheij and van de Knaap (2002) is used to describe the growth of a breach. For this formulation it is expected that the material of the levee (sand or clay), an initial breach width, the maximum breach depth and the period that is needed to reach this depth are known.
 
@@ -48,18 +51,96 @@ Once the minimum breach level is reached, the width of the breach increases acco
    \frac{\partial B}{\partial t}  |_t = \frac{f_1  f_2}{u_c^2 ln[10]}  \frac{[g(h_{up}(t) - h_{down}(t))]^{3/2}}{1 + \frac{f_2g}{u_c}(t - T_0) }   \qquad     t > T_0
 
 | In which:
-| :math:`f_1, f_2` empirically derived parameters, different per sediment type,
+| :math:`f_1, f_2` empirically derived parameters, different per sediment type (values for 3Di are given in table xxx),
 | :math:`u_c` is the critical velocity
-| :math:`h_{up}, h_{down}` is the water level upstream and downstream of the breach.
-|
+| :math:`h_{up}, h_{down}` is the water level upstream and downstream of the breach. 
+
+.. list-table:: Parameter values breaches 3Di
+   :widths: 40 40 40
+   :header-rows: 1
+
+   * - Parameter
+     - Clay
+     - Sand
+   * - :math:`f_1`
+     - 0.8
+     - 0.02
+   * - :math:`f_2` 
+     - 1.4
+     - 0.6
 
 Because the water level gradient in front and behind the breach is included in the formulation, a natural balance may arise. This means that the breach stops growing, when the water levels are equal.
 
 The above formulation also corrects for the presence of different types of materials by using a critical velocity and the parameters :math:`f_1` and :math:`f_2` . The growth rate of the breach increases for materials that erode more easily. In principle, this formulation distinguishes only sand and clay.
 
-Exchange formulation
-++++++++++++++++++++++++
+.. _breach_flow:
+
+Breach flow
++++++++++++
+
+3Di uses a broad-crested weir formulation for the flow rate through a breach. The figure below shows the main variables and the three flow domains used in these equations.
+
+.. figure:: image/b_breach_flow_domain.png
+   :alt: Breach flow domains
+
+Water flows from domain I to III. When the breach opens, domain I will be the river or sea water level; later in the event, the river or sea level may fall so low that the flow direction reverses, and the flooded area will become upstream (domain I). 
+
+| :math:`h_I` Upstream water level
+| :math:`h_{II}` Water level in the breach
+| :math:`h_{III}` Downstream water level
+| :math:`a` Crest level, i.e., Exchange level - Breach depth
+
+Which equation applies, depends on whether the flow is subcritical or (super)critical. The flow is (super)critical if the difference in water levels between domain I and III is greater than one-third of the water depth at the crest:
+
+.. math::
+   :label: when_supercritical_flow
+
+   (h_I - h_{III}) > \frac{1}{3}(h_I - a)
+
+Supercritical breach flow
+-------------------------
+
+For supercritical flow the following equation applies:
+
+.. math::
+   :label: super_critical_breachflow
+
+   u_{II} = \sqrt{\frac{2g(h_I-a)}{3(1-\gamma L)}}
+
+In which: 
+
+| :math:`v_{II}` flow velocity through the breach
+| :math:`g` gravitation constant
+| :math:`\gamma` friction loss term
+| :math:`L` Length of the breach (in the direction of the flow)
+
+For :math:`g`, 9.81 :math:`m/s^2` is used; for :math:`L`, the fixed value of 30 m is used for breaches, representative for most dikes. The friction loss term :math:`\gamma` is calculated as follows:
+
+| :math:`\gamma = \frac{c_f}{R}`
+| :math:`c_f = \frac{g}{C^2}`
+| :math:`R = \frac{A}{P}`
+| :math:`A = C_{Q}Wd_{II}`
+| :math:`P = W + 2h_{II}`
+| :math:`d_{II} = max(\frac{2}{3}(h_I-a),(h_{III}-a))`
+
+In which: 
+
+| :math:`c_f` friction coefficient, for breaches a fixed value of 50
+| :math:`R` hydraulic radius
+| :math:`A` wet cross-sectional area
+| :math:`P` wet radius
+| :math:`W` breach depth
+| :math:`C_Q` discharge coefficient
+| :math:`d_{II}` flow depth on the breach
+
+Subcritical breach flow
+------------------------
+
+When the flow is subcritical, the following equation applies:
+
+.. math::
+   :label: sub_critical_breachflow
 
-The flow between 1D and 2D at the breach is computed based on a simplified momentum balance. A balance is made between the friction and the forcing. Note, that the volume in the breach is neglected.
+   u_{II} = C_1*\sqrt{\frac{2g(h_I-h_{II}-a)}{(1-\gamma L)}}
 
-More details on how to use obstacles, levees and breaches can be found in :ref:`flood_model`.
+The variables used in this equation are identical to the variables used in the supercritical formulation and the :math:`\gamma` is calculated following the same equations as in the previous section.

source/h_flow.rst

@@ -3,7 +3,7 @@
 Flow
 ----
 
-In 3Di four different flow domains are defined. These domains are defined as :ref:`surface_flow`, :ref:`interflow`, :ref:`groundwater` and :ref:`onedee_flow`. The flow in these domains are computed based on conservation of mass and momentum. There are differences in the computation of the flow per domain. These are explained in the sections below.
+In 3Di, four different flow domains are defined: :ref:`surface_flow`, :ref:`interflow`, :ref:`groundwater` and :ref:`onedee_flow`. The flow in these domains is computed based on conservation of mass and momentum. There are differences in the computation of the flow per domain. These are explained in the sections below.
 
 
 .. toctree::

source/h_results.rst

@@ -60,7 +60,7 @@ First the meta information of the computational grid is defined.
   Mesh2DNode_type: Type of 2D computational cell
 
   - Name: Type of 2D mesh node/face
-  - Types: surface_water_2d, grounwater_2d, groundwater_2d, open_water_boundary_2d, groundwater_boundary_2d
+  - Types: surface_water_2d, groundwater_2d, open_water_boundary_2d, groundwater_boundary_2d
 
 **Dimensions** Length of the arrays