Merge pull request #342 from nens/groundwater-2023

Documentation for recent additions to groundwater functionality

source/d_1d_objects.rst

@@ -252,6 +252,24 @@ Attributes
      - No
      - \-
      - *Deprecated*
+   * - Exchange thickness
+     - exchange_thickness
+     - decimal number
+     - No
+     - m
+     - The thickness of the porous layer that the water needs to flow through to reach the groundwater, see :ref:`1d2d_groundwater_exchange`
+   * - Hydraulic conductivity in
+     - hydraulic_conductivity_in
+     - decimal number
+     - No
+     - \-
+     - Hydraulic conductivity for water flowing from the groundwater to the channel, see :ref:`1d2d_groundwater_exchange`
+   * - Hydraulic conductivity out
+     - hydraulic_conductivity_out
+     - decimal number
+     - No
+     - \-
+     - Hydraulic conductivity for water flowing from the channel to the groundwater, see :ref:`1d2d_groundwater_exchange`
 
 
 When using the 3Di Schematisation Editor
@@ -812,6 +830,25 @@ Attributes
      - No
      - \-
      - *Deprecated*
+   * - Exchange thickness
+     - exchange_thickness
+     - decimal number
+     - No
+     - m
+     - The thickness of the (porous) pipe wall that the water needs to flow through to reach the groundwater (or v.v.), see :ref:`1d2d_groundwater_exchange`
+   * - Hydraulic conductivity in
+     - hydraulic_conductivity_in
+     - decimal number
+     - No
+     - \-
+     - Hydraulic conductivity for water flowing from the groundwater into the pipe, see :ref:`1d2d_groundwater_exchange`
+   * - Hydraulic conductivity out
+     - hydraulic_conductivity_out
+     - decimal number
+     - No
+     - \-
+     - Hydraulic conductivity for water flowing from the pipe into the groundwater, see :ref:`1d2d_groundwater_exchange`
+
 
 .. _manhole_notes_for_modellers:
 
@@ -1357,6 +1394,7 @@ When using the 3Di Schematisation Editor
 - To digitize a trajectory of multiple pipes, first digitize the manholes, fill in the bottom levels, and then draw the pipe trajectory over these manholes by adding a vertex at each of the manholes. The pipes that are generated will use the manhole's bottom levels as invert levels and the *connection nodes* and *manholes* will be added automatically.
 
 
+
 .. _pipe_notes_for_modeller:
 
 Notes for modellers

source/h_1d2d_exchange.rst

@@ -93,13 +93,6 @@ The figure below shows an embedded channel in the computational grid. 3Di fixes
    :figwidth: 300 px
    :alt: Embedded channel in a computational grid
 
-.. todo::
-
-   @Nici, van onderstaande tekst begrijp ik echt heel weinig. Kan jij dit herschrijven / aan mij uitleggen / weghalen?
-
-   The geometry is simplified based upon the 2D geometry. It also shows, indicated with the coloured, transparent hollows, which domain contribute to the volumes. As they can be shifted with respect to the 2D domain, recalculation by hand can be difficult. There is an option to define the length of interest of an embedded channel.
-   If the channel within a 2D computational cell is shorter than that length, that part of the channel is skipped. This is indicated by the red circle in the same figure.
-
 Storage in embedded nodes
 """""""""""""""""""""""""
 
@@ -116,8 +109,8 @@ 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.
 
+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
 ---------
@@ -159,7 +152,40 @@ For double connected elements this implies:
 
    A_{1D2D} = L_{1D2D} H_{1D2D} = L_{bank} H_{1D2D}
    
+
+.. _1d2d_groundwater_exchange:
+
+Exchange between 1D and groundwater
+-----------------------------------
+
+Groundwater (2D domain) can interact with channels and pipes (1D domain). The flow is governed by various parameters: the material of the pipe/channel, the surrounding soil of the groundwater, et cetera. 3Di focuses on the large scale effect of the interaction and not on the detailed micro-scale flow. 3Di computes the flux between the two domains based on a diffusive equation, similar to the Darcy equation:
+
+.. math::
+   :label: 1D2D groundwater exchange equation
+
+   Q_{1D2D} = -A_{1D2D} \kappa_{in/out} \frac{\partial \eta}{\partial \delta}
+
+| where:
+| :math:`Q_{1D2D}` is the discharge between the domains, positive direction is from the 1D domain to the 2D domain 
+| :math:`A_{1D2D}` is the wet cross-sectional area 
+| :math:`\kappa_{in/out}` is the hydraulic conductivity
+| :math:`\eta` is the water level gradient
+| :math:`\delta` is the exchange thickness
+
+The wet cross-sectional area is based on the length and the wetted perimeter of the 1D-element. This depends on the upstream water level and the cross-section definition of the 1D element. This is indicated in the figure below for a flux out of the 1D elements.
+
+.. figure:: image/h_1d2d_groundwaterexchange.png
+   :figwidth: 400 px
+   :alt: Sketch of 1D-2D groundwater exchange and the wetted perimeter in red depending on the flow direction.
+
+   Sketch of 1D-2D groundwater exchange and the wetted perimeter in red depending on the flow direction.
+
+Each exchange is forced by a water level gradient and scaled by the hydraulic conductivity. Depending on the pipe wall material or the channel bed characteristics, the incoming and outgoing flow rates can scale differently. Therefore, an incoming and an outgoing hydraulic conductivity value can be defined. Another scaling factor is the thickness of the pipe or the bed (e.g. the layer of leaves and other non-decomposed organic matter) of the channel.
+
+
 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`.
+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_boundary_conditions.rst

@@ -1,4 +1,4 @@
-.. _boundary_condtions:
+.. _boundary_conditions:
 
 Boundary conditions
 ===================
@@ -15,14 +15,16 @@ Types
 
 A boundary condition must define one variable, so that the computational core can calculate the flow based on the values of the neighbouring node or flowline. You can define one of the following variables in a boundary condition:
 
-* Water level
+* Water level, a user defines a water level (time series). This value is fixed at the boundary cell (1D domain) or for all cells along the boundary (2D surface and groundwater domains).
 
-* Flow velocity
+* Flow velocity, a user defines the flow velocity (time series). This value is fixed at the boundary cell (1D domain) or for all cells along the boundary (2D surface).
 
-* Discharge
+* Discharge, a user defines the discharge (time series). This value is fixed at the boundary cell (1D domain) or for all cells along the boundary (2D surface and groundwater domains). Please note, the total amount of water is the sum of the discharge over all boundary flow lines.
 
 * Water level gradient (Sommerfeld boundary)
 
+
+
 Time series
 -----------
 

source/h_subgrid.rst

@@ -13,9 +13,17 @@ Nowadays, detailed bathymetry information becomes more and more available.  Howe
 
    Examples of flow in a flume, where a slight change in bathymetry strongly affects the flow.
 
-The basic idea behind the subgrid method, is that water levels vary much more gradually than the bathymetry. In hydrodynamic computations, water levels are assumed to be uniform within a computational cell. Traditionally, this is also assumed for the bathymetry within such a cell. The subgrid-based approach allows the bathymetry to vary within one computational cell, while the water level remains uniform. In 3Di two grids are to be defined; a high resolution subgrid and a coarse(r) computational grid. All input data, such as the bathymetry, roughness and infiltration rates can be defined on the high resolution grid, while the computations are performed on the coarse computational grid. Volumes and cross-sectional areas are based using the high resolution bathymetry information. The variation of the bathymetry within a computational cell means that a cell can be dry, wet or partly wet. This approach has two implications:
+The key assumption of the subgrid method, is that water levels vary much more gradually than the bathymetry. In most methods used for hydrodynamic computations, water levels are assumed to be uniform within a computational cell. Traditionally, this is also assumed for the bathymetry within such a cell. The subgrid-based method allows the bathymetry to vary within a computational cell, while the water level remains uniform. In 3Di, two grids are defined; a high resolution *subgrid* and a coarser *computational grid*. 
 
-- The volume has a non-linear relation with the water level, because when the water level rises, the wet surface area increases is well. Such a system can be solved using a newton iteration. To compute the volumes at the next time step.
+All input data, such as the bathymetry, roughness and infiltration rates, can be defined on the high resolution grid, while the computations are performed on the coarse computational grid. Volumes and cross-sectional areas are calculated using the high resolution bathymetry information. The variation of the bathymetry within a computational cell, related to a 2D surface water cell means that a cell can be dry, wet or partly wet. 
+
+For groundwater computational cells, the depth of the impervious layer is assumed to be uniform. The storage capacity in a groundwater cell is based on the high resolution bathymetry information. This implies that a groundwater cell can also be dry, partly full or completely full. This happens when the groundwater level reaches the highest level of the bathymetry within a computational cell.
+
+The subgrid method has three implications:
+
+- The storage capacity in the 2D surface and groundwater domains are grid size independent. 
+
+- The volume of a computational cell is a non-linear relation with the water level, because when the water level rises, the wet surface area changes as well. 
 
 - As we are allowed to have a non-linear relation between water level and volume, 3Di can deal automatically with flooding and drying. No artificial thresholds are necessary.
 
@@ -26,17 +34,13 @@ The basic idea behind the subgrid method, is that water levels vary much more gr
 
    An example of a computational cell with a bathymetry defined on the subgrid.
 
-Input
------
-
-Users define for the grid generation a cell size (of the finest grid resolution) and the number of refinement layers. A computational cell consists always of an even number of subgrid cells. In addition, the user needs to define where and if refinements should be defined. One can define polygons or lines to indicate these areas and the refinement level.
 
 .. _subgrid_tables:
 
 Subgrid tables
 --------------
 
-The high resolution subgrid data is compressed in tables that allow fast access during the simulation. These tables describe the relation between water level and the following variables: 
+The use of high resolution information also means that more data is used during the simulation. 3Di stores this data in subgrid tables to limit the memory usage and allow fast access during the simulation. These tables describe the relation between water level and the following variables: 
 
 * Volumes per computational cell (1D, 2D)
 * Cross-sectional area per half of cell face (2D)
@@ -62,7 +66,7 @@ increasing the linearization of the system and simplifying the mathematical equa
 The maximum distance between height increments is determined by the pixel values. This way, we prevent generating height increments for which each subsequent table entry would
 only linearly increase with respect to the previous table entry, thereby omitting an opportunity for data reduction and gain in computational speed. The exceptions are 
 tables with a non-linear relation regarding water depths, for example for friction tables. Interpolation between table entries that are too far apart will cause a loss in numerical
-precision due to the non-linear friction profile. 3Di can be forced to use a *Maximum table step size*; if not set, the maximum table step size is 100 × the table step size.
+precision due to the non-linear friction profile. 3Di can be forced to use a *Maximum table step size*; if not set, the maximum table step size is 100 times the table step size.
 
 
 .. figure:: image/table_2d_increments.png