Water Overlay: Difference between revisions

From Tygron Preview Support Wiki
Jump to navigation Jump to search
← Older edit
 
(668 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{learned|what the Water Overlays are|how to configure the Water Overlays}}
A Water Overlay is a [[Grid Overlay|grid overlay]] for which results are calculated by the [[Water Module]]. The [[Water_Module_Basics|Basic theory of the Water Module]] in the {{software}} is an implementation of a 2D grid based shallow water model based on the 2D Saint Venant equations. The module is further enhanced with infiltration, evaporation, groundwater flow and hydraulic structures. Depending on the use case, the simulated period can be set to few seconds and up to a few months. The [[Water_Module_Theory|theory]] section describes in detail how calculations are performed.
__NOTOC__
To perform the calculations, the project area is divided into a [[Grid overlay|grid of cells]]. Each cell has a specific quantity of water and specific hydrological parameters based on the data in the project. The total time which should be simulated is divided into discrete [[Timestep formula (Water Overlay)|timesteps]]. Per timestep, each cell communicates with its adjacent cells to exchange water, based on its water level, surface height, current flow direction and other factors. Accuracy and reliability is obtained by dividing the project area and simulation time into sufficiently small cells and steps, at the cost of more computation time.


==What are the Water Overlays==
The final results of the calculation can be inspected, as well as intermediate snapshots of the hydrological situation during the simulation, known as [[Timeframes (Water Overlay)|timeframes]].
With the Water Overlays the following overlays are meant:
* [[Rainfall_(Overlay)|Rainfall Overlay]]
* [[Flooding_(Overlay)|Flooding Overlay]]
* [[Groundwater_(Overlay)|Groundwater Overlay]]


Each of these overlays have some common configuration steps which will be described on this page.
==Variants==
 
A Water Module will be initialized by adding one of the following Overlays to a project. Each variant has a number of parameters tuned to best fit specific use-cases. This means that each of these overlays is based on the same theory and calculation method, however they are customized to conveniently provide insight in different aspects of the Water Module.  
==Tips on creating a new project when working with the Water Overlays==
When creating a new project in the [[Wizard|new project wizard]], take into account the [[Terrain_height#Terrain_height_in_the_Tygron_Platform|Advanced options]]. In this menu for example the [[GEO_Data|AHN3]] dataset can be selected, which, if available for your project area, provides the most recent heightdata available as Open Data. Also, the [[GEO_Data|IMWA]] dataset is already checked, this means that if available in your project area, Water Level areas and/or Culverts are already imported.
 
==Configuration==
When first added to the project, each variant of the water overlay will be created with a default configuration which will allow for an initial calculation to take place and results to display. For most use-cases, it is desirable to add additional data and tweak the settings and parameters of the overlay. This will improve the accuracy and relevancy of the overlay. It is possible to configure the parameters manually, or by using the configuration wizard.
 
===Configuration wizard===
<!--[[File:Config_wizard.JPG|900px]]-->The configuration wizard is a special interface which helps to guide the configuration of the overlay. Across multiple steps, it progresses through each type of {{inlink|data}} which can be configured, along with the most important {{inlink|attributes}} of the overlay.
 
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=Configuration wizard}}
 
Each of the water overlay variants has a configuration wizard which helps the user with configuring the overlay. The general structure of the wizard is the same for all variants, with the exception that for [[Flooding_(Overlay)|flooding overlays]] a [[breach]] area can be configured as well.
 
When the wizard has been completed once, it can be reopened at any time, and any step can be accessed anew.
 
====Step 1: Weather====
The {{inlink|weather|weather event}} defines the total simulation time and the weather and climate effects during the simulation. Specifically, the amount of rain and when it falls during the simulation, as well as the evaporation which takes place.
====Step 2: Water system====
The water system is the most complex step of the configuration, and contains a multitude of substeps to configure all geographical data. In order, the following data can be configured:
: '''Breach''' ([[Flooding_(Overlay)|flooding overlays]] only): A {{inlink|Breach|breach}}, a location where an (uncontrolled) inflow of water takes places, can be [[Geo Data Wizard|imported]] or connected to the hydrological model.
: '''Water areas''': {{inlink|Water level area}}s, defined regions in which a specific water level is maintained, can be [[Geo Data Wizard|imported]] or connected to the hydrological model. It is also possible to have the wizard generate a single water level area for the entire project area.
: '''Ground water''': {{inlink|Ground water}}, the height of the underground saturated by water, relative to {{datum}}. A [[GeoTIFF]] can be [[Geo Data Wizard|imported]].
: '''Sewers''': {{inlink|Sewer area}}s, the broad definitions for where what kind of sewert exist, can be [[Geo Data Wizard|imported]] or connected to the hydrological model. It is also possible to have the wizard generate sewer areas based on the [[neighborhood]]s in the project area.
: '''Inundation areas''': {{inlink|Inundation| Inundation area}}s, definitions of water on the surface, in the forum of inundated land, can be [[Geo Data Wizard|imported]] or connected to the hydrological model. It is also possible to have the wizard generate a single inundation area covering the entire project area.
 
: '''Weirs''': {{inlink|Weir}}s, minor barriers in the water flow, can be [[Geo Data Wizard|imported]] or connected to the hydrological model.
: '''Culverts''': {{inlink|Culvert}}s, tunnels which form direct connections between two locations, can be [[Geo Data Wizard|imported]] or connected to the hydrological model.
: '''Pumps''': {{inlink|Pump}}s, structures which move water from a lower to a higher location, can be [[Geo Data Wizard|imported]] or connected to the hydrological model.
: '''Inlets''': {{inlink|Inlet}}s, structures which add or remove water, can be [[Geo Data Wizard|imported]] or connected to the hydrological model.
: '''Sewer overflows''': {{inlink|Sewer overflow}}s, points where water from sewers can flow back onto the surface, can be [[Geo Data Wizard|imported]] or connected to the hydrological model.
 
====Step 3: Hydrological coefficients====
Hydrological coefficients are values of existing elements of the world, specifically {{inlink|terrain}} and {{inlink|constructions}}. The coefficients dictate the ability of water to flow between cells and layers. The following data can be configured:
: '''Surface terrain''': For the surface {{inlink|terrain}}s, attributes can be adjusted directly.
: '''Underground terrain''': For the underground {{inlink|terrain}}s, attributes can be adjusted directly as well.
: '''Constructions''': For {{inlink|constructions}}, the wizard links to the [[function values]] editing screen, and will open it the "WATER" filter for the values to display.
 
====Step 4: Interaction====
The wizard provides a few options to automatically generate methods of interaction with the hydrological model. The {{inlink|System visualization|system visualization}} can be activated or deactivated. Additionally, for some hydrological constructions and features panels can be generated which allow for their most important attributes during a [[session]].<!--
: '''System visualisation''':
: '''Interaction panels''':
-->
 
====Step 5: Output overlays====
Multiple {{inlink|Result types|result types}} can be selected. In the wizard multiple result types can be selected. One result type (indicated with the "First" checkbox) will be the main overlay's result type. The other selections will become {{inlink|Result child overlays|result child overlays}}. Relevant attributes can be modified as well, if they are related to selected result types.
 
Finally, the {{inlink|TIMEFRAMES}} attribute can be configured here as well, defining the amount of result snapshots which should be made during the calculation.
 
====Step 6: Input overlays====
To gain more insight into the data used by the model, you may opt to add one or more input overlays as well. These add [[Average_(Overlay)|average overlay]]s configured for the geographical display of attribute values relevant for the calculation of the water model.
 
===Manual configuration===
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay}}
 
====Grid overlay settings====
{{main|Grid overlay}}
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=General tab}}
 
Like all grid overlays, the water overlays have a number of configuration options related to their general method of calculation. Most notably, it is possible to configure the cell size on which the calculations occur.
 
The grid cell size can be changed by selecting "Change Grid". The minimum and maximum grid cell size depend on the project size. A larger cell size will allow for faster calculations. A smaller cell size will produce more detailed results.
 
====Result type====
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=General tab}}
 
The water model performs complex calculations, and multiple types of results can be provided. In principle, each overlay can be configured to display a single result type.
 
Result types can differ in the kind of data they display, the layer (surface or underground) of which they display that information, and how that data is recorded. Different result types can monitor data in the following ways:
* {{Anchor|Start_resulttype}}'''Start''': The data is determined at the start of the simulation, and does not change afterwards.
* {{Anchor|Last_resulttype}}'''Last''': The data is the latest value determined at the timestep the data is recorded. The values can increase and decrease between different timesteps. This mode is primarily used for monitoring progression.
* {{Anchor|Maximum_resulttype}}'''Maximum''': The data is the highest value determined up until the timestep the data is recorded. The values can only increase or stay the same, but will never decrease. This mode is primarily used to gain insight into impact; the most severe situation any point had to endure.
* {{Anchor|Total_resulttype}}'''Total''': The result of a running tally, counting the relevant data up until the timestep the data is recorded. The value can only increase or stay the same, but will never decrease. This mode is primarily used to gain insight into quantities rather than duration.
 
The following results types are available:
{| class="wikitable"
! Result type
! Unit
! Display mode
! Description
|-
|{{anchor|BASE_TYPES|BASE_TYPES}}
|Nominal value
|{{inlink|Start_resulttype|Start}}
|Categorization of the individual cells based on how they are processed by the water model, displaying which cells are considered to be specific features.<br>
0: Cell on the edge of the project area<br>
1: Water area<br>
2: Land<br>
3: Sewer<br>
4: Water object<br>
5: Breach Area<br>
6: Active Breach
|-
|{{anchor|CHLORIDE|CHLORIDE}}
|x/m²
|{{inlink|Last_resulttype|Last}}
|The amount of chloride present. The value is the sum of the quantities on the surface, and the underground.
|-
|{{anchor|DIRECTION|DIRECTION}}
|Degrees
|{{inlink|Last_resulttype|Last}}
|The direction in which water is flowing.
|-
|{{anchor|EVAPORATED|EVAPORATED}}
|m (mm)&sup1;
|{{inlink|Total_resulttype|Total}}
|The amount of water that has evaporated. The value is the sum of the quantities evaporated from the surface and the underground.
|-
|{{anchor|GPU OVERVIEW|GPU OVERVIEW}}
|nominal integer
|{{inlink|Maximum_resulttype|Maximum}}
|Shows which GPU cluster calculated which part of the overlay.
|-
|{{anchor|IMPACTED_BUILDINGS|IMPACTED_BUILDINGS}}
|nominal integer
|{{inlink|Maximum_resulttype|Maximum}}
|Constructions impacted by excess water. Constructions are considered impacted when the construction itself or an adjacent cell contains more water on the surface than configured in {{inlink|IMPACT_FLOOD_TRESHOLD_M}}.<br>
0: Construction is not impacted<br>
1...N: The {{inlink|Critical structures|(critical) construction}} is impacted, and has a critical [[function value]] set to this value.
|-
|{{anchor|LAST SPEED|LAST SPEED}}
|m/s
|{{inlink|Last_resulttype|Last}}
|The speed of water flow in any given location.
|-
|{{anchor|MAX SPEED|MAX SPEED}}
|m/s
|{{inlink|Maximum_resulttype|Maximum}}
|The speed of water flow in any given location.
|-
|{{anchor|NITROGEN|NITROGEN}}
|x/m²
|{{inlink|Last_resulttype|Last}}
|The amount of nitrogen present. The value is the sum of the quantities on the surface, and the underground.
|-
|{{anchor|PHOSPHORUS|PHOSPHORUS}}
|x/m²
|{{inlink|Last_resulttype|Last}}
|The amount of phosphorus present. The value is the sum of the quantities on the surface, and the underground.
|-
|{{anchor|SEWER_LAST_VALUE|SEWER_LAST_VALUE}}
|m (mm)&sup1;
|{{inlink|Last_resulttype|Last}}
|The amount of water stored in the sewer.
|-
|{{anchor|SEWER_MAX_VALUE|SEWER_MAX_VALUE}}
|m (mm)&sup1;
|{{inlink|Maximum_resulttype|Maximum}}
|The amount of water stored in the sewer.
|-
|{{anchor|SURFACE_DURATION|SURFACE_DURATION}}
|s (min)&sup1;
|{{inlink|Total_resulttype|Total}}
|The amount of time the water depth on the surface exceeds {{inlink|SHOW_DURATION_FLOOD_LEVEL_M}}.
|-
|{{anchor|SURFACE_FLOW|SURFACE_FLOW}}
|m&sup3;/m&sup2;
|
|''Description wil be added'' <!--Total volume of water passed a grid-cell, scaled by the cell surface (grid cell-size^2)-->
|-
|{{anchor|SURFACE_LAST_VALUE|SURFACE_LAST_VALUE}}
|m (mm)&sup1;
|{{inlink|Last_resulttype|Last}}
|The amount of water on the surface.
|-
|{{anchor|SURFACE_MAX_VALUE|SURFACE_MAX_VALUE}}
|m (mm)&sup1;
|{{inlink|Maximum_resulttype|Maximum}}
|The amount of water on the surface.
|-
|{{anchor|UNDERGROUND_FLOW|UNDERGROUND_FLOW}}
|m&sup3;/m&sup2;
|
|''Description wil be added'' <!--Amount of water which has infiltrated from the surface to the underground-->
|-
|{{anchor|UNDERGROUND_LAST_STORAGE|UNDERGROUND_LAST_STORAGE}}
|m (mm)&sup1;
|{{inlink|Last_resulttype|Last}}
|The (effective) amount of water in the underground unsaturated zone.
|-
|{{anchor|UNDERGROUND_LAST_VALUE|UNDERGROUND_LAST_VALUE}}
|m (mm)&sup1;
|{{inlink|Last_resulttype|Last}}
|The distance between the surface and the groundwater level.
|-
|{{anchor|UNDERGROUND_MAX_STORAGE|UNDERGROUND_MAX_STORAGE}}
|m (mm)&sup1;
|{{inlink|Maximum_resulttype|Maximum}}
|The (effective) amount of water in the underground unsaturated zone.
|-
|{{anchor|UNDERGROUND_MAX_VALUE|UNDERGROUND_MAX_VALUE}}
|m (mm)&sup1;
|{{inlink|Maximum_resulttype|Maximum}}
|The distance between the surface and the groundwater level.
|-
|{{anchor|UNDERGROUND WATERTABLE|UNDERGROUND WATERTABLE}}
|{{mdatum}}
|{{inlink|Last_resulttype|Last}}
|The groundwater level, relative to [[datum]].
|-
|{{anchor|WATER_STRESS|WATER_STRESS}}
|m (mm)&sup1;
|{{inlink|Maximum_resulttype|Maximum}}
|The amount of water on the surface, similar to {{inlink|SURFACE_MAX_VALUE}}. However, for water terrains, the water level must rise by at least {{inlink|ALLOWED_WATER_INCREASE_M}}. Otherwise, the value in those locations is 0.
|}
 
&sup1; the units between () are as displayed in the 3D client. If exported to GeoTiff the SI-convention is used: meters (m) and seconds (s).
 
=====Result child overlays=====
Each overlay can only display a single result type. When using a water overlay, it is conceivable that multiple result types are relevant to a project's use case. It's possible to duplicate the overlay, and set the copy of the overlay to a different result type, but this is not recommended. Downsides of this approach are that the simulation has to run in full multiple times, causing a severe increase in calculation time, and that when changes to the overlay's configuration have to be made those changes need to be made to all water overlays.
 
It is possible to add result child overlays overlays to a water overlay, which can display different results coming forth from the same calculation. The advantages of using result child overlays are that for any given water overlay, the calculation of the overlay only occurs once, rather than multiple times equal to the amount of desired result types. Additionally, the configuration for the calculation is only defined in a single overlay, which makes it easier to make sure all results come forth from the exact same simulation.
 
Result child overlays do not recalculate if either they or their parent is set to [[Grid_overlay#active|inactive]].
 
If a calculation overlay is removed, all result child overlays which are children of that overlay are removed as well. Separate overlays set as child overlays (such as [[Input overlays|input overlays]]) of the overlay will not be removed.
 
It is only possible to add result child overlays via the {{inlink|Configuration wizard|configuration wizard}}.
 
====System visualization====
 
==Data==
===Model connections===
The hydrological model can be linked to other models, which adds and defines more data for the simulation.
 
====Terrain height====
{{main|Terrain height}}
Terrain height is modeled in the form of an underlying grid, potentially amended by a [[GeoTIFF]].
 
The terrain height defines the height of the terrain on and in which the hydrology is modeled. Terrain height includes the relief on the surface of dry land, but also the height of the stream beds of water bodies.
 
Terrain height is a required and automatic connection. Each [[project]] has a terrain height model. By default the terrain height model will be derived from data sources relevant to the geographical location of the project area. However, especially in water bodies the level of detail of the terrain height may be insufficient. For these situations it's possible to load in an additional GeoTIFF of terrain heights.
 
{{GeoTIFFSpec
|title=Groundwater
|description=The height of the ground water level across the project area.
|nodata=Data is unchanged from the base terrain height.
|value=Groundwater level
|unit={{mdatum}}
}}
 
====Weather====
Weather in the {{software}} is modeled in the form of a [[weather|weather definition]].
 
[[Weather]] defines a number of environmental circumstances the hydrological model is subject to. It also defines the (total) {{inlink|simulation time}}.
 
Weather is a required connection. There is always exactly one weather connected to a water overlay, and by default if no weather exists an appropriate weather effect is created and connected automatically.
 
=====Rain and simulation time=====
Rain is a consistent addition of water to the hydrological model over a specified period of time. At the end of the rainfall's duration, the specified amount of rain will have fallen in each location in the project. The simulation can calculate both periods of rain as well as dry periods.
 
The total simulation time is composed of both the periods of rain, and the dry periods. It is possible to set up a simple, linear rainfall situation, in which a period of consistent rain is followed by a dry period. More complicated, custom configurations can be loaded in as well.
 
During a period of rain, the rainfall is constant. In each timestep an equal amount of water will fall, such that by the end of the period of rain that exact of rain will have fallen.
 
'''Linear configuration'''<br>{{RequestImage|description=Graph showing one period of rain, and one dry period. A second line showing the total amount of rain fallen up to that point. The total amount of time marked as simulation time.}}
When configuring a simple rainfall situation, it is possible to enter the properties for rain and simulation time by adjusting the linear properties. When using this method, the simulation will be composed of one period of rain, followed by one dry period.
{| class="wikitable"
{| class="wikitable"
! Property
|[[File:Overlay_rainfall.png]]
! Unit
|[[Rainfall_(Overlay)|Rainfall Overlay]]
! Description
|provides insight into the water stress and impact caused by (excessive) rainfall
|-
|Rain for
|minutes
|How long rain should last at the start of the simulation.
|-
|-
|Total rainfall
|[[File:Overlay_flooding.png]]
|mm
|[[Flooding_(Overlay)|Flooding Overlay]]
|How much rain should fall in the specified period.
|provides insight into water stress and impact caused by breaches in levees or other sources causing excessive water inflow
|-
|-
|Dry after rain (days, hours, minutes)
||[[File:Overlay_groundwater.png]]
|days, hours, minutes
|[[Groundwater_(Overlay)|Groundwater Overlay]]
|How long the simulation continues after the rain has fallen.
|provides insight into long-term processes of water flow both on the surface and underground
|}
|}
<!--==Input Data and Settings==
The calculations performed by the Water Overlay are influenced by many kinds of geographical information present in the project area. For any given location, [[terrain]], [[construction]]s and other features can influence either the initial state of the simulation or how water flows in a given area.


'''Custom configuration'''<br>{{RequestImage|description=Graph showing multiple periods of varying duration and varying rain intensities. A second line showing the total amount of rain fallen up to that point. The total amount of time marked as simulation time.}}
Furthermore, the Water Overlay features a number of overall settings which can be configured for the hydrological calculations and its results. These settings do not have a geographical or temporal element to them, and are fixed values relevant for the simulation as a whole.
If a use-case requires a more complex sequence of rain than a single period of rain followed by a single dry period, it is possible to prepare a [[comma-separated values]] file with a sequence of periods and values.
{{CSVSpec
|title=Rain and simulation
|line=Additional rainfall until specified moment
|criteria=<!--
-->Time should always be greater than or equal to previous time<!--
--><br>Rain should never be negative<!--
-->
|attribute=RAIN_M
|header1=Time|unit1=s
|header2=Rain|unit2=m
|l1e1=Time when first period ends|l1e2=Total rain during first period
|l2e1=Time when second period ends|l2e2=Total rain during second period
}}
The last time value also indicates the end of the simulation.
 
=====Evaporation=====
Evaporation is the consistent removal of water from the hydrological model over a specified period of time. As long as evaporation takes places at a certain rate, water both on the surface and underground can be subject to removal from the hydrological model. The evaporation rate defined by the weather is the base amount of evaporation for the {{inlink|Evaporation model|evaporation model}}.


'''Linear configuration'''<br>{{RequestImage|description=Graph showing constant amount of evaporation, and a fictive water amount decreasing consistently over time.}}
;[[Hydrologic_features_(Water_Overlay)|Hydrological features]]
When configuring a simple evaporation situation, it is possible to enter this property directly by adjusting the linear property. When using this method, the simulation will use a single rate of evaporation for the duration of the simulation.
:The water system can be enhanced with a number of hydrological features, which can be loaded in as [[area]]s. These hydrological features form special properties or modifications on the hydrological system. See [[Hydrologic_features_(Water_Overlay)|Hydological features]] for a list of supported features.
{| class="wikitable"
;[[Hydraulic structures (Water Overlay)|Hydraulic structures]]
! Property
:See [[Hydraulic structures (Water Overlay)|Hydraulic structures]] for the list of supported structures.
! Unit
;[[Additional_hydrological_attributes_of_buildings_(Water Overlay)|Hydrological attributes of buildings]]
! Description
:Besides the [[building]]s which directly influence the hydrologic model as a [[Hydraulic structures (Water Overlay)|hydraulic structure]], each building may also have attributes which can contribute to the hydrological model in some way. These attributes are stored and used on a grid cell level. This is different from the hydraulic structure attributes, which are stored and used on an object level. For a full list, see [[Additional_hydrological_attributes_of_buildings_(Water Overlay)|Additional hydrological attributes of buildings]].
|-
;[[Terrain_attributes_(Water_Overlay)| Hydrological attributes of terrain]]
|Surface evaporation
:[[Terrain]]s in a project have a number of hydrological attributes which can influence the flow of water in a project. Because there is always both surface and underground terrain defined for the entirety of the project area, all cells are affected by all attributes of terrains, unless a building is present with overwriting values. For a full list, see [[Terrain_attributes_(Water_Overlay)| Terrain attributes for the water overlay]].
|mm/day
;[[Model_attributes_(Water_Overlay)|Model settings]]
|The speed at which water evaporates during the simulation
:For a full list, see: [[Model_attributes_(Water_Overlay)|Water Model attributes]]
|}


'''Custom configuration'''<br>{{RequestImage|description=Graph showing varying amounts of evaporation in multiple periods, and a fictive water amount decreasing consistently over time with the speed of the evaporation.}}
==Troubleshoot, warnings and recommendations==
If a use-case requires a more complex pattern of evaporation than a single evaporation rate, it is possible to prepare a [[comma-separated values]] file with a sequence of periods and values.
When the Water Overlay is used and calculations take place, there are some problems or points of attention the calculation can run into. Where possible, the Water Overlay will show appropriate warnings when running into any issues.
{{CSVSpec
See [[Warning_and_recommendations_(Water_Overlay)|Troubleshoot, warnings and recommendations]];
|title=Evaporation
|line=Rate of evaporation until specified moment
|criteria=<!--
-->Time should always be greater than or equal to previous time<!--
--><br>Evaporation should never be negative<!--
-->
-->
|attribute=RAIN_M
|header1=Time|unit1=s
|header2=Evaporation|unit2=m
|l1e1=Time when first period ends|l1e2=Amount of evaporation during first period
|l2e1=Time when second period ends|l2e2=Amount of evaporation during second period
}}
====Ground water====
Ground water in the {{software}} is modeled in the form of a [[GeoTIFF]].
The hydrological model can simulate the {{inlink|underground model|underground}} environment as well. To enhance the level of detail of the underground environment, it is possible to connect a groundwater [[GeoTIFF]] to the water model. The ground water GeoTIFF will dictate the underground water levels relative to {{datum}} at the start of the simulation, influencing how much more water can be stored underground and how much water can flow from the underground.
Ground water is only a relevant connection when the {{inlink|underground model}} is active. If the ground water model is not active, a connection with a ground water model is not relevant, regardless of whether it's present or not.
Ground water is an optional connection. If no ground water is connected to the water model, the ground water level relative to {{datum}} is equal to the water level as defined by the {{inlink|water level areas}}.
{{GeoTIFFSpec
|title=Groundwater
|description=The height of the ground water level across the project area.
|value=Groundwater level
|unit={{mdatum}}
}}
====Subsidence====
Subsidence in the {{software}} is modeled in the form of a [[Subsidence_(Overlay)|subsidence overlay]].
The hydrological model is greatly influenced by the [[terrain height|height of the terrain]]. In virtually all cases water flows from higher places to lower places. The water model can be connected to a [[Subsidence_(Overlay)|subsidence]] calculation which affects the terrain height. This allows the model to take into account a period of subsidence which changes the terrain, and calculate the impact, effects, and flow in the future.
When a subsidence calculation is connected to the hydrological calculation, the outcome of the subsidence calculation affects the terrain height used by the hydrological calculations. The effect does not apply the other way around; output from the water model is not used as input or effect for the subsidence model.
Subsidence is an optional connection. If no subsidence model is connected to the water model, no subsidence is applied to the model prior to the calculations. Other effects on the terrain height, such as {{inlink|breach}}es, still apply.
===Hydrological features===
The water system can be enhanced with a number of hydrological features, which can be loaded in as [[area]]s. These hydrological features form special properties or modifications on the hydrological system.
====Water level area====
A water level area represents real-world water level areas. Within a water level area, the heights of all water [[terrain]]s are set to a specified level. {{RequestImage|description=An image (before)showing a terrain with part of it marked as water terrain. A second image (after) showing the same terrain, with the water terrain no longer specially marked but with a quantity of water on top. Both images have one valley marked as water terrain and another one which is regular terrain.}}
{| class="wikitable"
! Attribute
! Unit
! Description
! Default (when attribute is not present)
|-
|{{anchor|WATER_LEVEL|WATER_LEVEL}}
|{{mdatum}}
|The water level for all water terrains in this water level area
|n/a
|}
If no water level area is present in the project, the water level on water terrains is assumed to be extremely low. This allows water to flow into the open water areas at all times.
====Sewer area====
A sewer area is part of the definition of a system of sewers in the specified area. Sewer storage is present in the hydrological model wherever the sewer area intersects with a {{inlink|Sewered constructions|sewered construction}}.
{| class="wikitable"
! Attribute
! Unit
! Description
! Default (when attribute is not present)
|-
|{{anchor|SEWER_STORAGE|SEWER_STORAGE}}
|m
|The maximum height the water can reach in this sewer. This value, multiplied by the surface area of the sewered constructions the sewer area intersects with, forms the total amount of water this sewer can store.
|n/a
|-
|{{anchor|SEWER_PUMP_SPEED|SEWER_PUMP_SPEED}}
|m3/s
|The amount of water removed from the sewer by removing it from the hydrological model entirely.
|0
|}
Sewers don't have default storage amount, but when generating them automatically in the {{inlink|configuration wizard}}, suggested values are 0,007m for older sewers and 0,04 for newer sewers.
====Breach====
A breach is a modification to the [[terrain height]], with an optional in- or outflow of water for the hydrological model. This can be used to represent calamitous situations, such as a breach in a levee. Breaches can also be used to easily simulate a terrain height increase, effectively creating a levee.
A breach can either be defined solely as a terrain height modification using its {{inlink|BREACH_HEIGHT}} attribute, or as a connection to a water body outside of the hydrological model by adding attributes related to the external water body. If the breach is only defined as a terrain height change, only water that is already created or defined in some other way in the hydrological model can flow through and from it.
If the breach is given the attributes required for the external water body, water will automatically be created or removed uniformly on the breach, depending on the simulated water body "behind" the breach.
The breach can grow over time, based on its initial width and the critical speed at which water may flow. If a {{inlink|BREACH_WIDTH}} is defined, the breach's polygon is intersected with a circle emanating from the centerpoint of the polygon. It is only in that intersection, dubbed the "active breach" that the terrain height is considered lowered to the {{inlink|BREACH_HEIGHT}}. The radius of the circle defining the intersection will expand when the water flowing in from the external water body exceeds the {{inlink|BREACH_SPEED}}. Water flowing in the hydrological model across the breach's surface without explicitly entering or leaving the hydrological model does not "count" for the critical speed. All cells in the active breach are considered directly adjacent to the external water body.
If no critical speed is defined, the active breach will never grow. If no width is defined, the width is assumed to be very large, creating an intersection exactly the size of the polygon.
{| class="wikitable"
! Attribute
! Unit
! Description
! Default (when attribute is not present)
|-
|{{anchor|BREACH_HEIGHT|BREACH_HEIGHT}}
|{{mdatum}}
|The new [[terrain height]] at the location of the breach.
|n/a
|-
|{{anchor|BREACH_WIDTH|BREACH_WIDTH}}
|m
|The radius of the breach as drawn on the polygon defining the breach, emanating from the center point.
|10000
|-
|{{anchor|BREACH_SPEED|BREACH_SPEED}}
|m/s
|The speed at which water should flow through the breach before the width begins to increase.
|n/a
|-
|{{anchor|EXTERNAL_SURFACE_LEVEL|EXTERNAL_SURFACE_LEVEL}}
|{{mdatum}}
|The height of the bottom of the external water body behind the breach. The lowest level the external water level can lower to.
|0
|-
|{{anchor|EXTERNAL_WATER_LEVEL|EXTERNAL_WATER_LEVEL}}
|{{mdatum}}
|The water level of the external water body behind the breach. The initial level the water level is set to.
|0
|-
|{{anchor|EXTERNAL_AREA|EXTERNAL_AREA}}
|m²
|The surface area of the external water body behind the breach. The larger the external water body, the more water can flow from it, and the smaller the effect of the inflow or outflow of water on the external water level.
|n/a
|}
====Inundation====
An inundation is an initial placement of a quantity of water. This differs from the {{inlink|water level area}}s in that an inundation level allows you to place water anywhere on the surface.{{RequestImage|description=Same image as for water area, but in which the water terrain is already filled and the other valley isn't, but in the second image is filled with water.}}
{| class="wikitable"
! Attribute
! Unit
! Description
! Default (when attribute is not present)
|-
|{{anchor|INUNDATION_LEVEL|INUNDATION_LEVEL}}
|{{mdatum}}
|The height of the water.
|n/a
|}
===Hydrological constructions===
The water system can be enhanced with a number of hydrological [[construction]]s. These are constructions which effect water flow in specific cells, according to the parameters and rules of the constructions used. The effects of these constructions can be adjusted by setting the appropriate attributes.
Hydrological constructions can be either line-based or point-based:
* {{Anchor|Line-based constructions}}'''Line-based constructions'''<br>{{RequestImage|description=A simple polygon shape (rectangle), then the visualization of the skeleton lines, then the highlighting of the relevant endpoints.}}Line-based constructions form a direct connection between two exact cells, allowing water to flow from one point to another. The flow is dictated by the construction's formula. The endpoints of a line-based construction, the exact cells which are connected by the construction, are computed based on the orientation and size of their polygon. Essentially, the furthest ends of the polygon are used as end-points. Because the cells are considered adjacent, any calculated flow through line-based hydrological constructions is instantaneous.
* {{Anchor|Point-based constructions}}'''Point-based constructions'''<br>{{RequestImage|description=A simple polygon shape (square), then the visualization of the calculation of the centerpoint, and finally the highlighting of the endpoint.}}Point-based constructions add or remove water in one or more computational layers, based on their formula's. The centerpoint of a point-based construction, the exact cell where the effect takes place, is is the geometric center of the construction's polygon.
Note that the more complex the polygon is, the more difficult it is for the {{software}} to resolve it to a simple line or center point.
When the calculation of the water overlay completes, the total amount of water which has flowed through a specific construction is stored in an attribute in that construction. By default, this attribute is OBJECT_OUTPUT_FLOW, and the flow is expressed in m3. If multiple water overlays exist in the project simultaneously, the attribute name is appended with a number so that each overlay (as they are added to the project) has a unique attribute it writes its results to.
Hydrological constructions can only function as a single hydrological construction. If a single construction has attributes related to multiple hydrological constructions, the resulting behavior is undefined.
====Culvert====
Culverts are effectively tunnels or pipes directly connecting two bodies of water, and allow water to flow in either direction. Culverts can also be used to model tunnels on land, creating a hole which water can flow through when it is flowing over land. The throughput of a culvert is limited by its dimensions.
A culvert is a {{inlink|Line-based constructions|line-based construction}}.
{| class="wikitable"
! Attribute
! Unit
! Description
! Default
|-
|{{anchor|CULVERT_WIDTH|CULVERT_WIDTH}}
|m
|The diameter of the culvert. For throughput calculations, the culvert is assumed to have a spherical cross-section.
|1
|-
|{{anchor|CULVERT_HEIGHT|CULVERT_HEIGHT}}
|{{mdatum}}
|The height of the culvert. (When set to a level lower than the terrain for either endpoint of it, the culvert's height is equal to the height of the (highest) terrain under either endpoint.)
|0
|-
|{{anchor|CULVERT_N|CULVERT_N}}
|manning value
|The manning value of the culvert's material, which influences the flow speed.
|0,014
|}
====Weir====
Weirs are effectively small dams in the water, and allow water to flow from a water body with a higher water level to a lower water level. Any water exceeding the height of the weir can flow over it, increasing the throughput as the water level increases. Strictly, water can flow over the weir in either direction.
A weir is a {{inlink|Line-based constructions|line-based construction}}.
{| class="wikitable"
! Attribute
! Unit
! Description
! Default
|-
|{{anchor|WEIR_HEIGHT|WEIR_HEIGHT}}
|{{mdatum}}
|The height of the weir.
|n/a
|-
|{{anchor|WEIR_WIDTH|WEIR_WIDTH}}
|m
|The width of the weir.
|5
|-
|{{anchor|WEIR_COEFFICIENT|WEIR_COEFFICIENT}}
|coefficient
|The flow coefficient related to the shape of the weir
|1,1
|}
====Pump====
Pumps are constructions which can move water against its natural flow. Specifically, it moves water from the lower end of the pump to the higher end of the pump. The terrain height is used to determine the low end and the high end of the pump.
A pump is a {{inlink|Line-based constructions|line-based construction}}.
{| class="wikitable"
! Attribute
! Unit
! Description
! Default
|-
|{{anchor|PUMP_SPEED|PUMP_SPEED}}
|m3/s
|The speed at which water is pumped from the lower end-point to the higher end-point.
|n/a
|}
If a pump is placed such that both end-points are at locations with equal terrain height, the pump will be inactive and no water will flow through it.
====Sewer overflow====
Sewer overflows are points where water is moved from the sewer area to the above-ground water system. A sewer overflow will allow water to flow through if the water in the sewer exceeds the {{inlink|SEWER_OVERFLOW_THRESHOLD}}, and the water in the connected sewer exceeds the height of the terrain at the location of the sewer overflow. It will then function for all sewers part of that sewer area.
A sewer overflow is a {{inlink|Point-based constructions|point-based construction}}. It must intersect with a {{inlink|Sewer area|sewer area}}, but does not need to intersect with a an actual sewer.
{| class="wikitable"
! Attribute
! Unit
! Description
! Default
|-
|{{anchor|SEWER_OVERFLOW|SEWER_OVERFLOW}}
|{{mdatum}}
|The height of the bottom of the sewer, relative to the average terrain height of the connected sewer. Starting from this height, the water level in the sewer must exceed the height of the terrain at the location of the overflow in order for water to flow out.
|n/a
|-
|{{anchor|SEWER_OVERFLOW_SPEED|SEWER_OVERFLOW_SPEED}}
|m3/s
|The maximum speed at which water can flow out from the sewer through this overflow.
|10
|}
Note that at most one overflow can exist per sewer area.
====Inlet====
Inlets are points where water is either added to or removed from the hydrological model. It will add or remove water at a defined maximum rate, with optional thresholds for the amount of water to add or remove.
An inlet is a {{inlink|Point-based constructions|point-based construction}}.
{| class="wikitable"
! Attribute
! Unit
! Description
! Default
|-
|{{anchor|INLET_Q_constructions|INLET_Q}}
|m3/sec
|The maximum amount of water flowing into the model through this inlet. A negative value means the construction functions as an outlet, and water is removed from the hydrological model.
|n/a
|-
|{{anchor|INLET_CAPACITY_constructions|INLET_CAPACITY}}
|m3
|The maximum amount of water which can flow in or out through this construction. Water flowing back in the other direction replenishes the capacity.
|Infinite
|-
|{{anchor|LOWER_THRESHOLD_constructions|LOWER_THRESHOLD}}
|{{mdatum}}
|If a lower threshold is set, water will only flow into the model through this inlet until the water level at the point of this inlet is equal to or greater than the threshold. If the threshold is not set, the amount of water flowing in is not limited in this fashion.
|None
|-
|{{anchor|UPPER_THRESHOLD_constructions|UPPER_THRESHOLD}}
|{{mdatum}}
|If an upper threshold is set, water will only flow out the model through this outlet until the water level at the point of this inlet is equal to or lower than the threshold. If the threshold is not set, the amount of water flowing out is not limited in this fashion.
|None
|}
Note that all inlet attributes function as flow limits. If multiple are defined, water can flow in or out up until any of those limits are reached. If none are defined, no water flows in or out.
Also note that an inlet shares attribute names with the {{inlink|Breach|breach}}es, and that changing the attribute keys for inlets also affects the keys for breaches.
===Miscellaneous hydrological properties of {{anchor|constructions|constructions}}===
Besides the constructions which directly influence the main water flow in the hydrological model, all constructions have properties which may interact with the hydrological model in some way.
The effects of these constructions can be adjusted by setting the appropriate attributes. In some cases, these are attributes which relate to [[function value]]s. For these attributes, either can be adjusted to the same effect. Note that attributes which are connected to a function can be redefined, like the attribute names for {{inlink|hydrological constructions}} and {{inlink|hydrological features}} can be redefined.
In contrast with {{inlink|Hydrological constructions|hydrological constructions}} and their properties, all constructions can have any or all of the following miscellaneous effects on the hydrological model.
====Sewered constructions====
Sewered constructions are constructions under which a sewer exists, and through which water can flow into the sewer. When a sewered connection overlaps with a {{inlink|sewer area}}, that overlap forms an actual sewer, with the storage capacity of the {{inlink|SEWER_STORAGE}} attribute of the sewer area. Any surface water entering the cell of a sewered construction is directly moved to the sewer (unless the sewer is filled to capacity).
{| class="wikitable"
! Attribute
! Unit
! Function value
! Description
|-
|{{anchor|SEWERED|SEWERED}}
|boolean
|Connected to sewer
|Whether this construction is connected to the sewer.
|}
====Water storage constructions====
Constructions capable of water storage can store some surface water without allowing it to flow back into the rest of the model. Water stored in constructions can not flow out or evaporate away.
{| class="wikitable"
! Attribute
! Unit
! Function value
! Description
|-
|{{anchor|WATER_STORAGE|WATER_STORAGE}}
|m³/m²
|Water storage (m³/m²)
|How much water this construction can store.
|}
====Porous constructions====
Some constructions are porous or open, and can allow water to infiltrate into the underground unsaturated zone.
The speed at which water can infiltrate is dependent on both the infiltration properties of the constructions as well as on the underlying surface terrain. Of the infiltration values of the construction and the surface terrain, the lowest value is used. If either has an infiltration value of 0, water cannot infiltrate into the underground unsaturated zone.
{| class="wikitable"
! Attribute
! Unit
! Function value
! Description
|-
|{{anchor|GROUND_INFILTRATION_MD_constructions|GROUND_INFILTRATION_MD}}
|m/day
|Ground infiltration per day (m)
|The speed at which water can flow vertically from the surface to the underground unsaturated zone.
|}
====Crops and foliage====
Crops and foliage can draw water from the underground, allowing it to evaporate.
{| class="wikitable"
! Attribute
! Unit
! Function value
! Description
|-
|{{anchor|ROOT_DEPTH_M_constructions|ROOT_DEPTH_M}}
|m
|Depth of plant roots (m)
|The depth of the roots of this construction, relative to the terrain height at the location of this construction. Water can be drawn from the underground and evaporated if the roots can reach it.
|-
|{{anchor|WATER_EVAPORATION_FACTOR_constructions|WATER_EVAPORATION_FACTOR}}
|factor
|Water evaporation
|How fast this construction can evaporate water from the underground. The {{inlink|weather}}'s evaporation speed is multiplied by this factor to determine the rate of evaporation.
|}
Note that when a construction is present in any given location, the values for evaporation will overrule any values set by terrain in the same location. To model underground evaporation without a construction, set these attributes on the applicable terrain type instead.
====Critical structures====
Some constructions may be considered critical, meaning the consequences of water stress are greater for these structures than for others. Examples include hospitals and (elementary) schools. Critical constructions will receive additional highlighting by the {{inlink|IMPACTED_BUILDINGS}} result type when the building is impacted by the amount of water defined by {{inlink|IMPACT_FLOOD_THRESHOLD_M}}.
By using different values for differing (kinds of) constructions, it is possible to have impacted structures highlight with different values as well. This makes it possible to differentiate in greater detail between the kinds of impacted structures.
{| class="wikitable"
! Attribute
! Unit
! Function value
! Description
|-
|{{anchor|CRITICAL_INFRASTRUCTURE|CRITICAL_INFRASTRUCTURE}}
|nominal integer
|Critical infrastructure
|Whether this construction is deemed a critical construction. 0 means the construction is never deemed impacted.
|}
====Chemical emitters/decomposers====
Chemical emitters are constructions which produce specific chemicals. The net amount of chemicals a single construction creates is spread out across it's surface. After the chemicals are created, any water flowing through the same location will carry a part of the chemicals with it.
Structures which are defined to create a negative amount of chemicals function as a scrubber, removing the specified quantity of chemicals from the hydrological model.
In situations where water is absent, chemicals cannot move between cells.
{| class="wikitable"
! Attribute
! Unit
! Description
! Default
|-
|{{anchor|CHLORIDE_constructions|CHLORIDE}}
|x/m²
|The amount of chloride created per second per m² in this location.
|0
|-
|{{anchor|NITROGEN_constructions|NITROGEN}}
|x/m²
|The amount of nitrogen created per second per m² in this location.
|0
|-
|{{anchor|PHOSPHORUS_constructions|PHOSPHORUS}}
|x/m²
|The amount of phosphorus created per second per m² in this location.
|0
|}
Chemical emitters's attributes do not take the form of function values, and must be added manually<!--[[constructions#Adding_attributes]]--> or as part of [[Geo_Data_Wizard|loading in geodata]].
===Hydrological properties of {{anchor|terrain|terrain}}===
[[Terrain]]s in a project have a number of hydrological properties which can influence the flow of water in a project. The following attributes of terrains have effects on the hydrological model:
====Water====
Water terrains are processed by the water model in a specific manner before the simulation is started. For each water terrain in the 3D world, the bottom of the water body is treated as a land surface in the same fashion as dry land. Water is then placed on it on the surface {{inlink|layers|layer}}, up to the level defined by the overlapping {{inlink|Water level area|water area}}'s {{inlink|WATER_LEVEL}} attribute. Terrains not marked as water terrain are not initiated with water.
Terrains marked as water are subject to an additional check for the {{inlink|WATER_STRESS}} {{inlink|Result types|result type}}. If the amount of water on a water terrain has not increased by more than {{inlink|ALLOWED_WATER_INCREASE_M}} relative to the {{inlink|Water level area|water level area}}'s water level, that terrain will not count as stressed for that result type. The amount of water on that location must be at least {{inlink|ALLOWED_WATER_INCREASE_M}} more than the {{inlink|Water level area|water level area}}'s water level.
{| class="wikitable"
! Attribute
! Unit
! Terrain type
! Description
|-
|{{anchor|WATER|WATER}}
|boolean
|Surface
|Whether the specified terrain is a water terrain.
|}
====Evaporation{{anchor|Evaporation_terrain}}====
Terrains can be configured to draw water from the underground and evaporate it.
{| class="wikitable"
! Attribute
! Unit
! Terrain type
! Description
|-
|{{anchor|ROOT_DEPTH_M_surface|ROOT_DEPTH_M}}
|m
|Surface
|The depth of the roots of this surface terrain, relative to the surface. Water can be drawn from the underground and evaporated if the roots can reach it.
|-
|{{anchor|WATER_EVAPORATION_FACTOR_surface|WATER_EVAPORATION_FACTOR}}
|factor
|Surface
|How fast this terrain can evaporate water from the underground. The {{inlink|weather}}'s evaporation speed is multiplied by this factor to determine the rate of evaporation.
|}
Note that when a construction is present in any given location, the values for evaporation of the construction will overrule any values set by terrain in the same location. This is also true if the construction has its evaporation values set to 0; they will overrule the terrain's values and thus not allow evaporation of underground water to occur.
Also note that the groundwater level reduction is inversely proportional to the {{inlink|WATER_STORAGE_PERCENTAGE}}, as the contribution of a given volume of water to the groundwater level increases as the capacity for water storage in the underground layer decreases.
====Infiltration and storage====
Based on the properties of the terrain, water may infiltrate into the underground water system.
The speed at which water can infiltrate from the surface to the underground unsaturated zone is dependent on both the infiltration properties of the surface terrain, as well as any construction in that location, if present. Of the infiltration values of the construction and the surface terrain, the lowest value is used. If either has an infiltration value of 0, water cannot infiltrate into the underground unsaturated zone.
{| class="wikitable"
! Attribute
! Unit
! Terrain type
! Description
|-
|{{anchor|GROUND_INFILTRATION_MD_surface|GROUND_INFILTRATION_MD}}
|m/day
|Surface
|The speed at which water can flow vertically from the surface to the underground unsaturated zone.
|-
|{{anchor|GROUND_INFILTRATION_MD_underground|GROUND_INFILTRATION_MD}}
|m/day
|Underground
|The speed at which water can flow vertically from the underground unsaturated zone to the underground saturated zone, and horizontally through across the saturated zone.
|-
|{{anchor|WATER_STORAGE_PERCENTAGE|WATER_STORAGE_PERCENTAGE}}
|percentage
|Underground
|The percentage of the underground volume which can be filled with water. A lower percentage means the underground will be able to store less water, and the saturated zone will rise higher with the same amount of water in the underground layer.
|}
==Calculations==
===Models===
Multiple models are implemented which in conjuction form the water model in its entirety.
====Surface model====
The water model's primary function is the simulation of the flow of water on the surface of the terrain. The surface model includes the flow of water across the surface of the terrain, including over {{inlink|Water|water terrains}}, including the flow through {{inlink|Hydrological constructions|hydrological constructions}} and water that is created or removed by hydrological constructions.
The surface is defined by the {{inlink|Terrain height|terrain height}} in the project. The terrain height is further influenced by the height of constructions present in the project (bounded by {{inlink|DESIGN_FLOOD_ELEVATION_M}}) and by the {{inlink|SURFACE_OVERRIDE}} of {{inlink|breach}}es.
The surface water level is initialized based on hydrological features present in the project. For all {{inlink|Water|water terrains}}, water is placed on the surface of the world. The amount of water placed is such that the resulting water level in that location is equal to the {{inlink|WATER_LEVEL}} attribute of the {{inlink|Water level area}} in that location. If there is no water level area in that location, the water level is assumed to be so low that no water is created. Besides the water level areas, {{inlink|Inundation}} is added to the model. Water is placed in all locations where inundation is defined (regardless of the terrain type in that location, in contrast to the water level areas), such that the resulting height of the water inundating the land is equal to the inundation area's {{inlink|INUNDATION_LEVEL}} attribute.
After the surface is initialized with water, all water on the surface will flow in accordance with the same rules. It does not matter whether the water was created when the model was initialized, and whether that water was due to a water terrain or due to inundation, or whether the water came in from another source.
On the surface, water can flow from one cell to an adjacent cell based on the relative heights of the water, the slope of the terrain, and the manning value of the terrain or construction in that location.
In addition to water flowing between geographically adjacent cells, water can also flow through {{inlink|Hydrological constructions|hydrological constructions}}. When a {{inlink|Line-based_constructions|line-based hydrological construction}} exists in the project area, the 2 cells indicated by the endpoints of the line are considered adjacent as well. Flow between those cells is not dictated by the same parameters as the regular surface flow. Instead, water can flow between the 2 indicated cells based on the construction's underlying formula.
Water can also be added to or removed from the water model by {{inlink|Point-based_constructions|point-based hydrological constructions}}. Based on the construction's underlying formula water can be added or removed to the cell indicated by the construction. Only that single cell will receive or lose the calculated amount of water.
Water can also be removed from the surface by {{inlink|Miscellaneous hydrological properties of constructions|other properties}} of constructions, based on the construction's polygons (either moving it to another part of the hydrological model, or removing it completely from the hydorlogical model). When water is removed from the surface via a polygon-based construction, the removal of water is calculated per individual cell.
====Underground model====
The water model includes an underground model which dictates the movement of water in the soil. The underground model includes the flow of water from the surface into the underground via infiltration, the flow of water from one underground location to another, and the exfiltration of water from the soil back onto the surface layer.
The underground model can be explicitly activated or deactivated by setting the {{inlink|GROUND_WATER}} attribute of the water overlay to the appropriate value. If the underground model is deactivated, no water can move from or to the underground in any form, including {{inlink|Underground_evaporation_model|underground evaporation}}.
The underground is bounded vertically by the {{inlink|Surface model|surface of the terrain}} at the top, and an assumed impenetrable layer at the bottom. The distance between the surface and the impenetrable layer, and thus the effective height of the underground, is equal to {{inlink|GROUND_BOTTOM_DISTANCE_M}}. In other words, the impenetrable underground layer is assumed to be a set distance below the surface. The distance is uniform across the entire project area, and follows the profile of the surface.
The underground is composed of 2 layers: the unsaturated zone and the saturated zone. The saturated zone is the region of the underground where the soil is saturated with water. This water is assumed to work as a continuous volume of water able to flow horizontally. The unsaturated zone is the region of the underground above the saturated zone. The edge between the unsaturated and saturated zone can be considered the groundwater level.
The groundwater level, and thus the height of the saturated zone, is determined both by the amount of water in the saturated zone, and the underground terrain's {{inlink|WATER_STORAGE_PERCENTAGE|WATER_STORAGE_PERCENTAGE}}. The lower the water storage percentage of the soil, the greater the volume of soil that is saturated by the same amount of water, and thus the higher the the groundwater level will become.
The underground water level is initialized with the values of the {{inlink|Ground water GeoTIFF}} connected to the water model. If no ground water data is connected, the ground water level relative to {{datum}} is equal to the surface water level relative to {{datum}}, as defined by the {{inlink|WATER_LEVEL}} attribute of the {{inlink|Water level area}} in that location.
When water infiltrates from the surface, it infiltrates at a speed dictated by the surface terrain's {{inlink|GROUND_INFILTRATION_MD_surface|GROUND_INFILTRATION_MD}} attribute, or (if present) by the construction's {{inlink|GROUND_INFILTRATION_MD_constructions|GROUND_INFILTRATION_MD}}, whichever value is lower. If a highly porous constructions is present above a non-porous surface terrain, or the other way around, the lower infiltration value of either will cause the water to infiltrate slower despite the porous properties of the other.
Surface water infiltrates into the underground unsaturated layer. Water in the unsaturated layer is assumed to be spread equally across the entire unsaturated volume. Water then flows from the unsaturated zone into the saturated zone at the speed dictated by the underground terrain's {{inlink|GROUND_INFILTRATION_MD_underground|GROUND_INFILTRATION_MD}}. For a given timestep, the distance the water travels is determined. The amount of water that flows from the unsaturated zone to the saturated zone is equal to the amount of water in a section of the unsaturated zone the height of which is equal to that distance. After water has been added to the saturated zone, the groundwater level (and thus the height of the saturated zone) is redetermined. The water in the unsaturated zone is redistributed uniformly across the (remaining) unsaturated zone.
Water stored in the underground saturated zone can flow horizontally from one underground cell to another, if the groundwater level relative to {{datum}} is higher than the neighboring cell's ground water level, relative to {{datum}}. The amount of water which can flow from one cell to another is dictated by the underground terrain's {{inlink|GROUND_INFILTRATION_MD_underground|GROUND_INFILTRATION_MD}}.
Water stored in the underground saturated zone can also exfiltrate out of the underground and back onto the surface, if the groundwater level relative to {{datum}} exceeds the neighboring cell's surface water level relative to {{datum}}. The amount of water which can flow from the underground of one cell onto the surface of an adjacent cell is dictated by the underground terrain's {{inlink|GROUND_INFILTRATION_MD_underground|GROUND_INFILTRATION_MD}}.
====Rain model====
Rain is implemented in the water model.
Rain can be implicitly activated and deactivated by defining an appropriate period of {{inlink|Rain and simulation time|rainfall}}. If a period with no rainfall is defined, that period is simulated but no rain is simulated.
Currently, during a period in the simulation where {{inlink|Rain and simulation time|rainfall}} is defined, water is uniformly added to the {{inlink|Surface model|surface}} of all cells in the project area. During any single defined period of rain, the amount of rain is consistent over time. At the end of the defined period of rain, exactly the defined amount of rain will have fallen on each cell.
====Evaporation model====
Water can evaporate from the hydrological model over time. Multiple forms of evaporation are implemented.
All forms of evaporation can be implicitly activated and deactivated by setting the {{inlink|Weather|weather}}'s {{inlink|Evaporation|evaporation rate}}. If the evaporation factor is set to 0, no evaporation will take place in any form.
The weather's evaporation rate is defined as a period during which a certain rate of evaporation will take place. Multiple periods of evaporation can be defined, and at any specific moment during the simulation an exact evaporation rate is defined by the weather.
For all forms of evaporation, the weather's evaporation rate is used as a base for determining the exact rate of evaporation for that form of evaporation.
=====Surface evaporation model=====
Water can evaporate from the {{inlink|Surface_model|surface}}, based on the {{inlink|Weather|weather}}'s {{inlink|Evaporation|evaporation factor}} and the overlay's {{inlink|SURFACE_WATER_EVAPORATION_FACTOR}}. These values compute to a net rate of evaporation which is applied to the surface of all cells. Only water on the surface of cells is affected by this evaporation.
Cells without water on the surface are not affected by evaporation.
=====Underground evaporation model=====
Water can evaporate from the {{inlink|Underground_model|underground}} if the cell has either a {{inlink|Crops and foliage|construction which allows for underground evaporation}}, or a {{inlink|Evaporation terrain|surface terrain type}} which allows for underground evaporation and is unobstructed by a construction. In other words: if a construction is present the construction's properties are used, otherwise the terrain's properties are used.
Underground evaporation can be implicitly activated or deactivated by setting the relevant properties of all terrain types and constructions to appropriate evaporation values. If the relevant properties are set to 0, no underground evaporation will take place. Underground evaporation is also explicitly deactivated when the {{inlink|Underground_model|underground_model}} is deactivated.
Water can evaporate from the underground via crops and foliage. It can draw water from the underground unsaturated and saturated zones, if their roots reach deep enough and the terrain or construction have a configured evaporation factor. Water is drawn directly from the underground and evaporated, removing it from the hydrological model entirely.
The rate of evaporation is determined by the {{inlink|Weather|weather}}'s {{inlink|Evaporation|evaporation factor}}, and either the construction's {{inlink|WATER_EVAPORATION_FACTOR_constructions|WATER_EVAPORATION_FACTOR}} or the surface terrain's {{inlink|WATER_EVAPORATION_FACTOR_surface|WATER_EVAPORATION_FACTOR}}.
Evaporation can only take place if the roots of the terrain or construction can reach underground water. The depth the roots can reach is defined by either the construction's {{inlink|ROOT_DEPTH_M_constructions|ROOT_DEPTH_M}} or the surface terrain's {{inlink|ROOT_DEPTH_M_surface|ROOT_DEPTH_M}}.
Water can be evaporated both from the saturated and the unsaturated zones of the underground. The amount of water that can be taken from the saturated and the unsaturated zones is limited by the amount of water in either zone in reach of the roots.
====Sewer model====
Sewers are available in the water model, allowing for the retention of excess water which would otherwise stay and flow on the surface.
Sewers can be implicitly activated and deactivated by adding or removing {{inlink|Sewer area|sewer area}}s. If no sewer areas exist, no sewers are available in the water model and no water can flow to and from there.
Sewer areas define the areas in which sewers exist. The capacity of those sewers is based on the sewer area's {{inlink|SEWER_STORAGE}} attribute. The actual locations where the sewer exists is the intersection between the sewer areas and the {{inlink|Sewered constructions|sewered constructions}} in the project area. The total surface area of the actual sewer is equal to that intersection.
If there is water on the {{inlink|Surface model|surface}}, in a cell with a sewered construction, and there is a sewer present in the same location, the water flows directly into the sewer. Water can flow in until the sewer is filled to capacity. Water can only flow into a sewer a via sewered construction. It is not possible for water to flow from a sewer back to the surface via a sewered construction, unless that construction is is explicitly a sewer overflow.
Water can flow from a sewer overflow back onto the surface via a {{inlink|Sewer overflow|sewer overflow}}. A sewer overflow removes water from the sewer and places it on the surface of the cell where the overflow is located. The speed at which this water flows is determined by the {{inlink|SEWER_OVERFLOW_SPEED}}.
To overflow from the sewer to the surface, two criteria need to be met. Firstly, the amount of water in the sewer relative to the sewer's total capacity must exceed the {{inlink|SEWER_OVERFLOW_THRESHOLD}}. Secondly, the water level in the sewer must exceed the terrain height at the location of the sewer overflow.
Water can be removed from a sewer based on the sewer area's {{inlink|SEWER_PUMP_SPEED}}. Water removed from the sewer in this way is removed entirely from the hydrological model.
====Storage model====
Water on the {{inlink|Surface model|surface model}} can be stored in {{inlink|Water storage constructions|water storage constructions}}.
Water storage in constructions can be implicitly activated or deactivated by ensuring that all constructions in the project area have appropriate water storage properties. If there are no constructions in the project area with water storage capacity, no water storage will take place.
When water flows onto a cell with a {{inlink|Water storage constructions|construction capable of storing water}}, that water will be stored in the construction until the construction's water storage capacity has been reached. Water cannot leave that storage, either through flow back into the hydrological model or by being removed from it altogether. When the storage is filled, no additional water cannot flow into that storage for the remainder of the simulation.
====Chemical flow model====
Chemicals can be modeled in the hydrological model, as quantities picked up and carried along with the water.
The chemical model can be implicitly activated and deactivated by having construction in the project area have the appropriate attributes configured. If no constructions have attributes configured to interact with the quantities of chemicals, then no chemicals are computed.
Chemicals are tracked as an exact amount on a given location. The exact unit and magnitude is not defined in the {{software}}, as the calculations for chemicals function the same for all magnitudes.
Chemicals are added to the hydrological model and removed from the hydrological model by {{inlink|Chemical emitters/decomposers|chemical constructions}}. The chemicals created are then placed on the {{inlink|Surface model|surface}} of the cells where they are created. Chemicals can also be removed by chemical constructions, if their attributes are configured appropriately. When chemicals enter the cell which contains a chemical decomposer, the chemicals are removed from the hydrological model.
When water moves from a cell which also contains chemicals, the chemicals are carried along with the water. The chemicals are uniformly distributed between the water which remains in the cell, which flows to other cells, which infiltrates, and which is removed or stored. Water which flows into the sewer explicitly cannot carry chemicals along with it.
====Model border====
The outer edge of cells of the water model are excluded from calculations. No water can flow from or to there.
===Formulas===
====Timestep formula====
An adaptive timestep is implemented according to Kurganov and Petrova (2007)<ref name="Kurganov1" />. At every timestep, the courant-number is kept smaller than 0.25 for every active computation cell.
[[File:Inundation_overlay_03.PNG|400px]]
Especially at low depths, choosing the appropriate timestep is critical to avoid numerical instability. Therefore the following principles are used to determine the right time step:
* the timestep is choosen so that all computation cells follow one of the following criteria.
* if a cells waterdepth is below the flooding threshold, 5 * 10<sup>-3</sup> (m) there is no flow assumed between that cell and it neigboring cell.
* if the cells waterdepth is above above the flooding threshold, the maximum timestep is assumed to be 100 * the waterdepth at the cell.
* if the waterdepth increases, the timestep is assumed to be not larger than the formula above.
If the numerical flux decreases, larger timesteps are allowed than set by Kurganov and Petrova<ref name="Kurganov1" />, depending on the {{inlink|Calculation_preference_formula|configured calculation}}.
====Calculation preference formula====
The calculation preference influences the calculation of individual timesteps.
: ''Δt  = Δx /u<sub>max</sub>''
Where:
* Δt = computational timestep
* Δx = grid cell size
* u<sub>max</sub> = max velocity, assumed 2.5 (SPEED), 5 (AVERAGE) and 10 (ACCURACY) m/s respectively
====Surface water level formula====
Surface water level is calculated per cell.
: ''WL<sub>surface</sub> = W<sub>surface</sub> + H<sub>surface</sub>''
Where:
* WL<sub>surface</sub> = The water level, relative to {{datum}}.
* W<sub>surface</sub> = The amount of water (the water column) on the surface.
* H<sub>surface</sub> = The terrain height in the cell, relative to {{datum}}.
====Surface flow formula====
Surface flow is calculated using the 2D Saint Venant equations.
=====2D Saint Venant=====
The base equations describe the conservation of mass and momentum in both the x and y direction.
[[File:Inundation_overlay_01.PNG|350px]]
The following processes are described in these equations:
* friction
* bed slope
* water pressure
* convection (changes in bathemetry over space)
* inertia (increase or decrease of velocity over time)
=====Numerical scheme for the 2D Saint Venant equations=====
[[File:Inundation overlay 04 HWP(1).PNG|thumb|250px|Source: Horváth et al. (2014)<ref name="Horvath"/>]]
[[File:Inundation overlay 04 HWP(2).PNG|thumb|250px|Source: Horváth et al. (2014)<ref name="Horvath"/>]]
The explicit second-order semi-discrete central-upwind scheme for the 2D Saint Venant Equations is implemented. A reconstruction of cell bottom, water level and velocity at the interfaces between computational cells as proposed by Lax and Wendroff (Rezzolla, 2011)<ref name="Rezolla"/>. The {{software}}'s [[water model]] relies on the scheme described in Kurganov and Petrova (2007)<ref name="Kurganov2"/>. The reconstruction method is taken from Bolderman et all (2014) and ensures numerical stability at the wetting and drying front of a flood wave<ref name="Bollerman" />.
A clear explanation on the numerical approach can be found at Horváth et al. (2014)<ref name="Horvath"/>, but in general it follows these steps:
# The elevation value of the cell (denoted as B in included figures) is equal to the elevation value at the center of the cell. At the same time, it is equal to the average value of the elevation values at the cell interface midpoints.
# The slopes of the conserved variables (denoted as U in included figures), continuity and momentum in x and y direction, are reconstructed.
# Values of conserved variables at the cell interface midpoints are compared with the left-sided and right sided values at cell centers.
# At partially dry cells, the slope is modified to both avoid negative depths and numerical instability.
# (Numerical) fluxes are computed at each cell interface to determine the values of the conserved variable at the cell centers for the next time-step.
{{clear}}
====Groundwater level formula====
Groundwater level is calculated per cell.
: ''WH<sub>underground</sub> = W<sub>sat</sub> / WSP''
: ''WL<sub>underground</sub> = WH<sub>underground</sub> + H<sub>surface</sub> - GBDM''
Where:
* WL<sub>underground</sub> = The groundwater level, relative to {{datum}}.
* WH<sub>underground</sub> = The height (column) of the saturated zone.
* W<sub>sat</sub> = The amount of water in the saturated zone. The height of the water column if the equivalent amount of water was placed on the surface.
* H<sub>surface</sub> = The terrain height in the cell, relative to {{datum}}.
* GBDM = The {{inlink|GROUND_BOTTOM_DISTANCE_M}}(effectively available height in the underground model).
* WSP = The {{inlink|WATER_STORAGE_PERCENTAGE}} of the underground terrain type.
====Surface infiltration formula====
Surface infiltration is calculated per cell.
Infiltration capacities:
: ''C<sub>water</sub> = W<sub>surface</sub>''
: ''C<sub>top</sub>'' = max( I<sub>con</sub>, I<sub>surf</sub> )
:: I<sub>surf</sub> = 0 if a construction is present
:: I<sub>con</sub> = 0 if no construction is present
Actual infiltration:
: ''Δw =  min( C<sub>water</sub> , Δt * C<sub>top</sub>)''
Where:
* Δw = The surface infiltration which takes place.
* Δt = Computational timestep.
* C<sub>water</sub> = The amount of infiltration that can take place based on the amount of water on the surface.
* C<sub>top</sub> = The amount of evaporation that can take place based on the infiltration values present.
* W<sub>surface</sub> = The amount of water (the water column) on the surface.
* I<sub>con</sub> = The {{inlink|GROUND_INFILTRATION_MD_constructions|GROUND_INFILTRATION_MD}} of a construction on a specific cell (if present).
* I<sub>surf</sub> = The {{inlink|GROUND_INFILTRATION_MD_surface|GROUND_INFILTRATION_MD}} of the surface terrain type. This value should be interpreted as the vertical conductivity (Kv) of the sub-soil.
====Underground infiltration formula====
Underground infiltration (from the unsaturated zone to the saturated zone) is calculated per cell.
First the height of the unsaturated zone is calculated.
: ''H<sub>unsat</sub> = H<sub>surface</sub> - WL<sub>underground</sub>''
Then the ratio of water amount to unsaturated height is calculated.
: ''S = W<sub>unsat</sub>/H<sub>unsat</sub>''
Then calculate the distance of the unsaturated zone which can infiltrate.
: ''C<sub>inf</sub> = min( H<sub>unsat</sub> , Δt * I<sub>und</sub> )''
Finally, calculate the amount of actual amount of water infiltrating.
: ''Δw = C<sub>inf</sub> * S''
Where:
* Δw = The underground infiltration which takes place.
* Δt = Computational timestep.
* H<sub>unsat</sub> = The height of the unsaturated zone.
* S = Ratio of water to height in the unsaturated zone.
* C<sub>inf</sub> = The height in the unsaturated zone which can be subject to infiltration to the saturated zone.
* W<sub>unset</sub> = The amount of water in the unsaturated zone. The height of the water column if the equivalent amount of water was placed on the surface.
* WL<sub>underground</sub> = The groundwater level, relative to {{datum}}.
* H<sub>surface</sub> = The terrain height in the cell, relative to {{datum}}.
* I<sub>und</sub> = The {{inlink|GROUND_INFILTRATION_MD_underground|GROUND_INFILTRATION_MD}} of the underground terrain type.
====Underground flow formula====
Underground flow between cells is calculated using Darcy's law<ref name="Modflow"/>.
: ''C<sub>d</sub> = Δt * I<sub>und</sub> * width * A * ( (WL<sub>source</sub> - WL<sub>target</sub>) / distance )
Since both ''width'' and ''distance'' are directly related to the cell size, and the result should be in water height rather than volume, the formula can be rewritten as follows:
: ''C<sub>d</sub> = Δt * I<sub>und</sub> * A * (W<sub>source</sub> - W<sub>target</sub>) / cell
Because the underground may have a different porousness, the maximum amount of water that can flow to another cell has to take into account the relative water storage capacities of the underground.
: ''C<sub>wsp</sub> = (WL<sub>source</sub> - WL<sub>target</sub>) * (WSP<sub>source</sub> / (WSP<sub>source</sub> + WSP<sub>target</sub>) )
The amount of water which flows from the source to the target cell is calculated as follows:
: ''Δw = max( 0 , min( C<sub>d</sub> , C<sub>wsp</sub> ) )
Where:
* Δw = The underground flow which takes place.
* Δt = Computational timestep.
* cell = Cell size.
* C<sub>d</sub> = The capacity for water flow possible based on the relative water heights.
* C<sub>wsp</sub> = The capacity for water flow possible based on the relative water storage percentages.
* WL<sub>source</sub> = The amount of water in the saturated zone of the source cell. The height of the water column if the equivalent amount of water was placed on the surface.
* WL<sub>target</sub> = The amount of water in the saturated zone of the target cell. The height of the water column if the equivalent amount of water was placed on the surface.
* A = Contact area of the underground cells
* I<sub>und</sub> = The {{inlink|GROUND_INFILTRATION_MD_underground|GROUND_INFILTRATION_MD}} of the underground terrain type of the origin cell.
* WSP<sub>source</sub> = The {{inlink|WATER_STORAGE_PERCENTAGE|WATER_STORAGE_PERCENTAGE}} of the underground terrain type of the origin cell.
* WSP<sub>target</sub> = The {{inlink|WATER_STORAGE_PERCENTAGE|WATER_STORAGE_PERCENTAGE}} of the underground terrain type of the target cell.
====Culvert formula====
<!--Culvert flow is calculated based on the 2 end-point cells.-->
====Weir formula====
====Pump formula====
The flow created by a pump is calculated based on the lowest end point of the pump.
: ''Δw = min( W<sub>lower</sub> , Δt * PS )''
Where:
* Δw = The amount water water pumped from the lower to the higher endpoint.
* Δt = Computational timestep.
* W<sub>lower</sub> = The water amount of water (the water column) at the lower end point.
* H<sub>lower</sub> = The terrain height at the lower end point, relative to {{datum}}.
* PS = The {{inlink|PUMP_SPEED}} of the pump.
====Overflow formula====
Overflow from the sewer is calculated for the entirety of the sewer, and the single attached sewer overflow.
Overflow can take place when:
: ''H<sub>sewer</sub> + SO - H<sub>overflow</sub> &gt; 0''
Actual overflow:
: ''Δw = min( 0 , WH<sub>sewer</sub> * Σ<sub>sewer</sub> , Δt * SOS )''
where:
* Δw = The amount of sewer overflow which takes place.
* Δt = Computational timestep.
* Σ<sub>sewer</sub> = The surface area of the sewer.
* WH<sub>sewer</sub> = The water height sewer.
* H<sub>sewer</sub> = The average height of the terrain where the sewer is present, relative to {{datum}}.
* H<sub>overflow</sub> = The height of the terrain at the centerpoint of the sewer overflow, relative to {{datum}}.
* SO = The {{inlink|SEWER_OVERFLOW}} attribute of the sewer overflow.
* SOS = The {{inlink|SEWER_OVERFLOW_SPEED}} attribute of the sewer overflow.
====Inlet formula====
The amount flowing in or out of inlets is calculated for the cell the inlet resides on.
When calculating '''inlets''', first the capacities are calculated.
If a T<sub>lower</sub> is defined:
: ''C<sub>inthres</sub> = max( 0 , T<sub>lower</sub> - WL<sub>surface</sub> )''
If a I<sub>Q</sub> is defined:
: ''C<sub>speed</sub> = Δt * I<sub>Q</sub>''
If a C<sub>total</sub> is defined:
: ''C<sub>incap</sub> = C<sub>used</sub> - C<sub>total</sub>''
After calculating the capacities, the actual water inflow is calculated.
: ''Δw = max( 0 , min( C<sub>inthres</sub> , C<sub>speed</sub> , C<sub>incap</sub> ) ) / cell''
: If any of the terms are undefined, they are not included.
When calculating '''outlets''', first the capacities are calculated.
If a T<sub>lower</sub> is defined:
: ''C<sub>outthres</sub> = min( 0 , T<sub>upper</sub> - WL<sub>surface</sub> )''
If a I<sub>Q</sub> is defined:
: ''C<sub>speed</sub> = Δt * I<sub>Q</sub>''
If a C<sub>total</sub> is defined:
: ''C<sub>outcap</sub> = -C<sub>total</sub> - C<sub>used</sub>''
After calculating the capacities, the actual water ouflow is calculated.
: ''Δw = min( 0 , max( C<sub>outthres</sub> , C<sub>speed</sub> , C<sub>outcap</sub>) ) / cell''
: If any of the terms are undefined, they are not included.
After the water flow (either inflow or outflow) is computed, the capacity is updated.
: ''C<sub>used</sub> (new) = C<sub>used</sub> (old) + (Δw * cell)''
Where:
* Δw = The amount of water flow which takes place.
* Δt = Computational timestep.
* cell = Cell size.
* C<sub>speed</sub> = The amount of water inflow (or outflow when negative) possible based on the inlet's {{inlink|INLET_Q}} attribute.
* C<sub>incap</sub> = The amount of water inflow possible based on the total {{inlink|INLET_CAPACITY|capacity}} of the inlet.
* C<sub>outcap</sub> = The amount of water outflow possible based on the total {{inlink|INLET_CAPACITY|capacity}} of the outlet.
* C<sub>inthres</sub> = The amount of water inflow desired based on the inlet's {{inlink|LOWER_THRESHOLD}} attribute.
* C<sub>outthres</sub> = The amount of water outflow desired based on the outlet's {{inlink|UPPER_THRESHOLD}} attribute.
* WL<sub>surface</sub> The water level on the surface, relative to {{datum}}.
* C<sub>total</sub> = The {{inlink|INLET_CAPACITY}} attribute of the inlet.
* I<sub>Q</sub> = The {{inlink|INLET_Q}} attribute of the inlet.
* T<sub>lower</sub> = The {{inlink|LOWER_THRESHOLD}} attribute of the inlet.
* T<sub>upper</sub> = The {{inlink|UPPER_THRESHOLD}} attribute of the inlet.
====Surface evaporation formula====
Surface evaporation is calculated per cell.
: ''Δw = min( WL<sub>surface</sub> , Δt * E<sub>weather</sub> * E<sub>overlay</sub> )''
where:
* Δw = The amount of evaporation which takes place.
* Δt = Computational timestep.
* W<sub>surface</sub> = The amount of water (the water column) on the surface.
* E<sub>weather</sub> = The {{inlink|Evaporation|evaporation rate}} of the weather.
* E<sub>overlay</sub> = The {{inlink|SURFACE_WATER_EVAPORATION_FACTOR}}.
====Underground evaporation formula====
Underground evaporation is calculated per cell.
Evaporation capacities:
For all underground evaporation, the height of the unsaturated zone is used.
: ''H<sub>unsat</sub> = H<sub>surface</sub> - WL<sub>underground</sub>''
First the capacity for saturated evaporation is calculated, based on how much of the saturated area is in contact with the roots.
: ''C<sub>sat</sub> = max( 0 , min( RD , GBDM ) - H<sub>unsat</sub> ) * WSP''
Next the height of the unsaturated zone, and based on that the capacity for unsaturated evaporation is calculated.
: ''C<sub>unsat</sub> = max( 0 , min( RD , H<sub>unsat</sub> ) ) * ( W<sub>unsat</sub> / H<sub>unsat</sub> )''
Finally, the actual evaporation is calculated:
: ''Δw<sub>unsat</sub> = min( C<sub>unsat</sub> , Δt * E<sub>weather</sub> * E<sub>top</sub> )''
: ''Δw<sub>sat</sub> = min( C<sub>sat</sub> , (Δt * E<sub>weather</sub> * E<sub>top</sub>) - Δw<sub>unsat</sub> )''
: ''Δw = Δw<sub>unsat</sub> + Δw<sub>sat</sub>''
Where:
* Δw = The total amount of evaporation which takes place.
* Δt = Computational timestep.
* Δw<sub>unsat</sub> = The amount of evaporation which takes place from the unsaturated zone.
* Δw<sub>sat</sub> = The amount of evaporation which takes place from the saturated zone.
* C<sub>sat</sub> = The amount of evaporation that can take place from the saturated zone.
* C<sub>unsat</sub> = The amount of evaporation that can take place from the unsaturated zone.
* H<sub>unsat</sub> = The height (column) of the unsaturated zone.
* W<sub>unsat</sub> = The amount of water in the saturated zone. The height of the water column if the equivalent amount of water was placed on the surface.
* WL<sub>underground</sub> = The groundwater level, relative to {{datum}}.
* H<sub>surface</sub> = The terrain height in the cell, relative to {{datum}}.
* RD = The {{inlink|ROOT_DEPTH_M_constructions|ROOT_DEPTH_M}} of the construction if present, the {{inlink|ROOT_DEPTH_M_surface|ROOT_DEPTH_M}} of the surface terrain otherwise.
* GBDM = The {{inlink|GROUND_BOTTOM_DISTANCE_M}} (effectively available height in the underground model).
* E<sub>weather</sub> = The {{inlink|Evaporation|evaporation rate}} of the weather.
* E<sub>top</sub> = The {{inlink|WATER_EVAPORATION_FACTOR_constructions|WATER_EVAPORATION_FACTOR}} of the construction if present, the {{inlink|WATER_EVAPORATION_FACTOR_surface|WATER_EVAPORATION_FACTOR}} of the surface terrain otherwise.
===Computational structure===
====Order of operations====
Calculations are performed in the following order:
* Horizontal surface flow and horizontal underground flow
* Rain
* Building storage
* Sewer inflow
* Surface evaporation
* Groundwater evaporation (saturated zone)
* Groundwater evaporation (unsaturated zone)
* Underground infiltration
* Surface infiltration
* Exfiltration
====Calculation time impacts====
==General Tab==
[[File:General_tab.JPG|250px|right|The geberal tab of the Water Overlays.]]
The General Tab can be found at the panel on the right side, when selecting a Water Overlay. In this tab several settings can be adjusted.
===Calculation Preference===
Here you can manipulate the computation time step by choosing between the option SPEED, AVERAGE and ACCURACY. The computational timesteps will be set according to the Courant criterion:
Δt  = Δx /u<sub>max</sub>
where:
* Δt = computational timestep
* Δx = grid cell size
* u<sub>max</sub> = max velocity, assumed 2.5 (SPEED), 5 (AVERAGE) and 10 (ACCURACY) m3/s respectively
===Grid cell size===
The {{software}} computes flow equations over a rectangular cartesian grid, the grid cell size can be set by clicking on Change Grid.
After the grid cell size is changed, the Overlay is immediately being recalculated.
Note: if you choose a smaller grid cell size, both the amount of time steps (see Calculation Preference) and amount of computational cells increase.
===Refresh Grid===
By Refreshing the grid, the Overlay is recalculated. This may take some time, depending on the grid cell size, the size of your project and the calcualtion preference.
Below some use cases when to use Refresh Grid:
* when you have changed a setting in the Configuration Wizard, but not clicked on the Finish button of the wizard.
* when you change the Result type or calculcation preference in the General tab
* when you change the legend in the Legend tab
* when you change the keys in the Keys tab
* when you change the attrbutes of the Overlay in the Attributes tab
===Export Grid File===
You can export the current result type as either a GeoTiff (binary file/bitmap image can be opened in a GIS or in an image viewer) or ASCII (text file, can also be opened in a GIS but is also readable in a text editor) file.
Also, it is possible to export the difference result type of the current and maquette situation.
===Save Overlay result===
With this option you can create a duplicate inactive copy of the current overlay. This is noticeable in the Overlays panel on the left side of the screen. The duplicated overlay will have (inactive copy) behind the overlay name and is greyed out. This copy is not being recalculated when changing settings in the original duplicated overlay. When checking the checkbox: active in simulation, the copy becomes active again and can be recalculated. Also the overlay name is again in black and not grayed out anymore.
===Show Water Balance===
The Water Balance panel shows the in- and outflow of water in m3. The Water Balance panel is also visible when clicking on the Debug info (see below).
The water balance is made up of the following components (depending on what is in the project):
* Land surface: amount of water on the land surface after simulation (m3)
* Water surface: amount of water stored on water cells after simulation (m3)
* Building storage: amount of water stored in building storage (m3)
* Sewer storage: amount of water stored in sewers after simulation (m3)
* Underground storage: amount of water stored in the sub-soil after simulation (m3)
* Evaporated: amount of water evaporated after simulation (m3)
* Outlet: amount of water extracted from the model during the simulation via outlets of water areas or sewer pumps (m3).
===Warnings===
When the grid cell size is too large in combination with the project size, a warning pops up. This means that calculated results are not accurate. The solution to this is to reduce the grid cell size.
===Debug Info===
The debug info contains the following information:
* Rain: the amount of rainfall (mm) in the duration of the rainfall event (hours)
* Total Simulation: the simulation period (hours)
* Cells: The dimensions of the simulation: the amount of computational cells and the amount of time steps (cycles)
* Water areas:
* Weir flow: the amount of water flown over weirs during simulation (m3)
* Sewer overflow: the amount of water flown over sewer overflows during simulation (m3)
* GPU time: the computation time on GPU (seconds)
* Volume: total volume of the in- and outflow of water in the model.
If you click on the Debug Info the Water Balance panel pops up.
==Keys tab==
The tab Keys refers to the settings for the water system (areas and constructions) that are adjusted by following the configuration wizard in the General tab. It is therefore generally not needed to change the keys in this tab, as most of the keys are adjusted via the configuration wizard. However, below an explanation of the Keys for areas and buildings.
{| class="wikitable"
! Attribute
! Unit
! Description
|-
|Water Level
|m + datum
|initial water level, relative to datum, for all water cells in a water area
|-
|Outlet
|m3/s
|water abstraction for all water cells in a water area
|-
|Outlet level
|m + datum
|initial water level, relative to datum, for all water cells in an outlet area (breach for example)
|-
|Outlet capacity
|m3
|maximum amount of water that can be used for the outlet
|-
|Sewer Storage
|m         
|available storage in sewers at the start of simulation in a sewer area
|-
|Sewer Pump Speed
|m3/s
|sewer water abstraction for all cells in a sewer area
|-
|Breach Floor
|{{mdatum}}
|Modified terrain height, to simulate a breach in a levee.
|-
|Inundation level
|{{mdatum}}
|Initial water height, to simulate water present at the start of the simulation.
|}
Keys referring to constructions (building attributes)
{| class="wikitable"
! Attribute
! Unit
! Description
|-
|Weir Height
|m + datum
|weir crest level
|-
|Weir Output
|m3/s
|The amount of water that flows through a weir/culvert
|-
|Weir Coefficient
|
|linear weir coefficient for accounting discharge & contraction losses
|-
|Culvert Speed
|m3/s
|the discharge capacity of a culvert
|-
|Pump Speed
|m3/s
|the capacity of a pump
|-
|Sewer Overflow Height
|m + datum
|the height of a crest of a sewer overflow
|-
|Sewer Overflow Speed
|m3/s
|the discharge capacity of a sewer overflow
|-
|Chloride
|x/m2
|Amount* of chloride which is created per second, per m² of construction with this attribute.
|-
|Nitrogen
|x/m2
|Amount* of nitrogen which is created per second, per m² of construction with this attribute.
|-
|Phosphorus
|x/m2
|Amount* of phosphorus which is created per second, per m² of construction with this attribute.
|-
|}
<nowiki>*</nowiki> The unit of the substances is left incomplete, as the project creator is free to set their own unit for quantities of substances.
==Attributes tab==
This tab shows the attributes of result types that can be adjusted. These attributes can also be adjusted in the configuration wizard in step 5 in the General tab. It is therefore generally not needed to change the attributes here. However, below an overview of the Overlay Attributes. <!--
The water model calculation's rely on a number of calculation-wide parameters. These parameters are available as attributes of the water overlay and can be modified as such.
-->
{| class="wikitable"
! Attribute
! Unit
! Description
|-
|{{anchor|ALLOWED_WATER_INCREASE_M|ALLOWED_WATER_INCREASE_M}}
|m
|The amount by which the water level on a water terrain must increase before it is considered stressed by water. This is used to compute the {{inlink|WATER_STRESS}} result type.
|-
|{{anchor|DESIGN_FLOOD_ELEVATION_M|DESIGN_FLOOD_ELEVATION_M}}
|m
|Constructions in the 3D world are assumed to have at most this height compared to the surface of the terrain. Greater values can create a more accurate model but will impact performance.
|-
|{{anchor|GROUND_BOTTOM_DISTANCE_M|GROUND_BOTTOM_DISTANCE_M}}
|m
|Assumed distance under the terrain surface where the soil becomes impenetrable for water. The groundwater level cannot go below this depth, relative to the surface. The maximum amount of water that can be stored underground is equal to this attribute multiplied by the local terrain's {{inlink|WATER_STORAGE_PERCENTAGE}}.
|-
|{{anchor|GROUND_WATER|GROUND_WATER}}
|boolean
|Whether underground water flow is simulated during the calculation. If this is deactivated, {{inlink|Surface infiltration model|surface infiltration}}, {{inlink|Underground infiltration model|underground infiltration}}, and {{inlink|Evaporation model|underground evaporation}} do not occur. Water flowing {{inlink|Sewer model|in- and out of the sewer}} are still simulated when sewers are present.
|-
|{{anchor|IMPACT_FLOOD_THRESHOLD_M|IMPACT_FLOOD_THRESHOLD_M}}
|m
|The amount of water a construction must experience before it is considered impacted by water. Water must reach this height either on one of the cells the construction is on, or on one of the cells adjacent to it. This is used to compute the {{inlink|IMPACTED BUILDINGS}} result type.
|-
|{{anchor|MAX_SPEED_MS|MAX_SPEED_MS}}
|m/s
|Maximum speed at which water is allowed to flow. This effects the preservation of impulse in water, and as a result the length of {{inlink|Computational timestep calculation|computational timesteps}}. Impulse is more accurately preserved as the maximum speed increases, but will reduce the time per step of the calculation, increasing the total time for the calculation to complete.
|-
|{{anchor|MIN_SLOPE|MIN_SLOPE}}
|ratio
|The minimum slope required to account for the effect of gravity on the speed of the water. If the slope of the terrain is less than the minimum slope, the effect of gravity on the speed of the water is assumed to be 0. The ratio is the height over distance.
|-
|{{anchor|SEWER_OVERFLOW_THRESHOLD|SEWER_OVERFLOW_THRESHOLD}}
|fraction
|How much of a sewer's storage must be filled with water before the {{inlink|Sewer overflow|sewer's overflows}} are allowed to overflow water.
|-
|{{anchor|SHOW_DURATION_FLOOD_LEVEL_M|SHOW_DURATION_FLOOD_LEVEL_M}}
|m
|The amount of water which must be present in a specific location before the duration of surface water can be recorded. This is used to compute the {{inlink|SURFACE_DURATION}} result type.
|-
|{{anchor|SUPERGRID|SUPERGRID}}
|
|This attribute name is reserved for future functionality. Currently, this marks an experimental feature which is currently under development and may result in unexpected behavior when activated.
|-
|{{anchor|SURFACE_WATER_EVAPORATION_FACTOR|SURFACE_WATER_EVAPORATION_FACTOR}}
|factor
|The factor by which the {{inlink|weather}}'s evaporation factor is multiplied to compute the amount of {{inlink|Evaporation model|evaporation}} which takes place on the surface.
|-
|{{anchor|TIMEFRAMES|TIMEFRAMES}}
|amount
|The number of intermediate results recorded during the calculation. Each timeframe becomes a snapshot of data which can be viewed and analysed. The total simulation time is divided by this value, and at each interval of that period of time a snapshot of the results so far is made. Note that the first timeframe does not contain the starting conditions of the simulation, but the state of the simulation after the first period of time has passed.
|}


==References==
==Results==
<references>
With a Water Overlay, a user can generate multiple [[Results_(Water_Overlay)|results]] for a single water simulation. For further information about these outcomes, see also [[Results_(Water_Overlay)|results]] and [[Result type (Water Overlay)|result types]].
<ref name="Kurganov1">Kurganov A, Petrova G (2007) ∙ A Second-Order Well-Balanced Positivy Preserving Central-Upwind Scheme for the Saint-Venant System ∙ p 15 ∙ found at: http://www.math.tamu.edu/~gpetrova/KPSV.pdf (last visited 2018-06-29)</ref>


<ref name="Horvath">Zsolt Horváth, Jürgen Waser, Rui A. P. Perdigão, Artem Konev and Günter Blöschl (2014) ∙ A two-dimensional numerical scheme of dry/wet fronts for the Saint-Venant system of shallow water equations ∙ found at: http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.700.7977&rep=rep1&type=pdf ∙ http://visdom.at/media/pdf/publications/Poster.pdf ∙ (last visited 2018-06-29)</ref>
==How-to's==
* [[How to add and remove an Overlay]]
* [[How to manually configure a Water Overlay|Configure a Water Overlay]]
* [[How to edit an overlay legend|Edit an overlay legend]]
* [[How to add Subsidence (Water Overlay)|Combine with Subsidence Overlay]]
* [[Water Model Limits]] (some basic rules)


<ref name="Rezolla">Rezzolla  L (2011) ∙ Numerical Methods for the Solution of Partial Differential Equations ∙ found at: http://www.scirp.org/(S(lz5mqp453edsnp55rrgjct55))/reference/ReferencesPapers.aspx?ReferenceID=1886006 (last visited 2018-06-29)</ref>
===Features and components===
* [[Hydrological features (Water Overlay)|Hydrological features]]
* [[Hydraulic structures (Water Overlay)|Hydraulic structures]]
* [[How to_manually_configure_a_Water_Overlay|Manual configuration Options]]
* [[Simulation data (Water Overlay)|Simulation data]]


<ref name="Kurganov2">Kurganov A, Petrova G (2007) ∙ A Second-Order Well-Balanced Positivy Preserving Central-Upwind Scheme for the Saint-Venant System ∙ found at: http://www.math.tamu.edu/~gpetrova/KPSV.pdf (last visited 2018-06-29)</ref>
===Attributes===
* [[Model attributes (Water Overlay)|Water Module Attributes]]
* [[Hydrological attributes of buildings (Water Overlay)|Hydrological Attributes of Buildings]]
* [[Hydrological attributes of terrains (Water Overlay)|Hydrological Attributes of Terrains]]


<ref name="Bollerman">Bollermann A, Chen G, Kurganov A and Noelle S (2014) ∙ A Well-Balanced Reconstruction For Wetting/Drying Fronts ∙ found at: https://www.researchgate.net/publication/269417532_A_Well-balanced_Reconstruction_for_Wetting_Drying_Fronts (last visited 2018-06-29)</ref>
{{WaterOverlay output nav}}
{{Overlay nav}}


<ref name="Modflow">Langevin, C.D., Hughes, J.D., Banta, E.R., Niswonger, R.G., Panday, Sorab, and Provost, A.M. (2017) ∙ Documentation
[[Category:Water Module]][[Category:Overlays with result types]]
for the MODFLOW 6 Groundwater Flow Model: U.S. Geological Survey Techniques and Methods, book 6, chap. A55 ∙ p 31 ∙ found at: https://doi.org/10.3133/tm6A55 (last visited 2019-02-04)</ref>
</references>

Latest revision as of 13:40, 17 January 2023

A Water Overlay is a grid overlay for which results are calculated by the Water Module. The Basic theory of the Water Module in the Tygron Platform is an implementation of a 2D grid based shallow water model based on the 2D Saint Venant equations. The module is further enhanced with infiltration, evaporation, groundwater flow and hydraulic structures. Depending on the use case, the simulated period can be set to few seconds and up to a few months. The theory section describes in detail how calculations are performed.

To perform the calculations, the project area is divided into a grid of cells. Each cell has a specific quantity of water and specific hydrological parameters based on the data in the project. The total time which should be simulated is divided into discrete timesteps. Per timestep, each cell communicates with its adjacent cells to exchange water, based on its water level, surface height, current flow direction and other factors. Accuracy and reliability is obtained by dividing the project area and simulation time into sufficiently small cells and steps, at the cost of more computation time.

The final results of the calculation can be inspected, as well as intermediate snapshots of the hydrological situation during the simulation, known as timeframes.

Variants

A Water Module will be initialized by adding one of the following Overlays to a project. Each variant has a number of parameters tuned to best fit specific use-cases. This means that each of these overlays is based on the same theory and calculation method, however they are customized to conveniently provide insight in different aspects of the Water Module.

Rainfall Overlay provides insight into the water stress and impact caused by (excessive) rainfall
Flooding Overlay provides insight into water stress and impact caused by breaches in levees or other sources causing excessive water inflow
Groundwater Overlay provides insight into long-term processes of water flow both on the surface and underground

Results

With a Water Overlay, a user can generate multiple results for a single water simulation. For further information about these outcomes, see also results and result types.

How-to's

Features and components

Attributes

Water Module
Water Module
Tutorials
Overview
Theory
Benchmarks
Group
Output keys
Object flow output • Object height output • Object datum output a • Object datum output b • Object width output
Output other
Result type • Water balance • System visualization • Weather visualization • Debug info
Related
Building attributes • Hydraulic structures • Hydrological features •  Terrain attributes • Model attributes • Simulation data
Overlays
Categorization
Grid • Parent • Result Child • Result Parent • Result type
Default
City
Administrative
Ownership • Ownership Grid • Zipcodes • Zoning • Neighborhoods • Municipalities • Vacancy
Environmental
Heat Stress • Traffic Density • Traffic Noise • Traffic NO2 • Livability
Water
Rainfall • Flooding • Groundwater • Subsidence • Watershed
Grid Calculation
Average • Combo • Distance • Sight Distance • Travel Distance • Inference • Iteration
Geo Data
GeoTIFF • WCS • WMS • Image • Area • Attribute • Function
Topography
Satellite • Digital Surface Model • Digital Terrain Model • Underground • Source
Network
Network Distance • Network Overview • Network Ownership
Retrieved from "https://previewsupport.tygron.com/w/index.php?title=Water_Overlay&oldid=49557"