Water Overlay: Difference between revisions

From Tygron Support wiki
Jump to navigation Jump to search
 
(163 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{learned|what the Water Overlay is|what use-cases the Water Overlay can be applied to|what data is required to fully configure the Water Overlay|what options are available to configure the Water Overlay|how to analyse the results of the Water Overlay|how the Water Overlay's functionality has been implemented}}
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.
==What is the Water overlay==
__NOTOC__
The water [[Overlay|overlay]] is an implementation of a large number of hydrological formulas which together can simulate the flow of water across large areas with a high level of detail. Its calculations form a simulation of an arbitrary amount of time, during which water is allowed to move.
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.


Water flow is affected by properties of the surface across which it flows, including the [[terrain height]] and the properties of the underlying [[terrain]].
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]].


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 {{inlink|Timestep formula|timesteps}}. Per timestep, every cell communicates with all adjacent cells to exchange water. By dividing the project area and simulation time into sufficiently small cells and steps the behavior becomes effective continuous.
==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.  
The final results of the calculation can be inspected, as well as snapshots of the hydrological situation in the simulation, known as {{inlink|lcase=1|Timeframes}}.
 
===Variants===
The water overlay can be added to a project as one of a number of variants. Each variant has a number of parameters tuned to best fit certain use-cases. The following preconfigured variants exist:
* [[Rainfall_(Overlay)|Rainfall Overlay]], provides insight into the water stress caused by (excessive) rainfall.
* [[Flooding_(Overlay)|Flooding Overlay]], provides insight into water stress caused by breaches in levees or other sources causing excessive water inflow.
* [[Groundwater_(Overlay)|Groundwater Overlay]], provides insight into long-term processes of water flow both on the surface and underground.
 
===Use cases===
{{main|Use cases Water Overlay}}
{{stub|type=section}}
The water overlay is complex and versatile, and can configured for a large number of different detailed use cases.
Due to the complexity of the water overlay, if an exact understanding of the functioning of the water overlay is not required or desired, it may be preferable to follow the instructions to complete one or more specific use cases, as found on the [[Use cases Water Overlay|water overlay's use cases page]].
 
==How to use the Water overlay==
<onlyinclude>{{#if:{{{how to use|<noinclude>main</noinclude>}}}|<!--
 
-->In general, when a water overlay is added to a project it will immediately be capable of calculating results. However, these will be based on default settings and will at best give a broad sense of water stress.
 
To use any variant of the overlay properly, it is recommended that you ensure the project meets a number of {{inlink|lcase=1|Prerequisites}}. Next, it is recommended to prepare all {{inlink|Data|data related to the hydrological model}}, which defines the functioning and flow of the water. Included in this preparation is a clear idea of the {{inlink|{{#if:<noinclude>main</noinclude>|Model connections|Calculation properties}}|climate conditions}} and what kind of {{inlink|{{#if:<noinclude>main</noinclude>|Result type|Result types}}|output}} is desired. After these preparations have been made, {{inlink|{{#if:<noinclude>main</noinclude>|Configuration|Adding and configuring the overlay}}|creation and configuration}} of the overlay can begin. When the configuration is completed, a [[Grid overlay#Grid recalculation|recalculation]] of the overlay will yield more accurate and appropriate results.
 
After the overlay has calculated results, a number of means exist to {{inlink|{{#if:<noinclude>main</noinclude>|Results|Data analysis}}|analyse the results}} of the calculation performed.<!--
 
-->|}}</onlyinclude>
 
===Prerequisites===
<onlyinclude>{{#if:{{{prerequisites|<noinclude>main</noinclude>}}}|<!--
 
-->When creating your [[project]], make sure it meets the following criteria:
* Your project has been loaded in with a high-resolution DEM. This can be configured during the [[Terrain_height#Terrain_height_in_the_Tygron_Platform|new project wizard]].
* Your project is large enough to account for {{#if:<noinclude>main</noinclude>|{{inlink|Model border|edge effects}}|[[Water_Overlays#Model border|edge effects]]}}.<!--
--><includeonly>
For more tips for preparation and use, see the [[Water Overlay#Additional tips for preparation and use|Water Overlay]] page.</includeonly><!--
 
-->|}}</onlyinclude>
 
===Additional tips for preparation and use===
<onlyinclude>{{#if:{{{tips|<noinclude>main</noinclude>}}}|<!--
 
-->There are a number of additional points of attention when creating a project with the intent of using this overlay:
* When creating a new project in the [[Wizard|new project wizard]], consider using the [[GEO_Data#AHN3|AHN3]] dataset rather than the default AHN2. Where coverage is available, the AHN3 dataset will be more accurate. Where coverage is not available, the default AHN2 should be used.
* Additionally, when creating a new project, consider whether you want to use the [[GEO_Data#IMWA|IMWA]] dataset for {{#if:<noinclude>main</noinclude>|{{inlink|lcase=1|Hydrological constructions}}|[[Water_Overlays#Hydrological constructions|hydrological constructions]]}}. Although this dataset is not complete, some information about constructions which serve as {{#if:<noinclude>main</noinclude>|{{inlink|lcase=1|Culvert}}|[[Water Overlay#Culvert|culvert]]}}s other relevant objects can be loaded in from this datasource. If more complete or accurate data is available to be loaded in into the project after it is created, it may be desirable to disregard this source so that hydrological constructions are not doubly included.
* Water flow can often be dictated by small features in an area, such as small openings between buildings, and thin [[levee]]s. To have these small features included properly in the calculations, the {{#if:<noinclude>main</noinclude>|{{inlink|Grid cell size configuration|grid cell size}}|[[Water Overlay#Grid cell size configuration|grid cell size]]}} will need to be set to an appropriate size. The default setting offered by the {{software}} will often need to be adjusted to allow for smaller features to be recognized without having their presence averaged out with their surroundings.
* The water overlay performs a complete simulation, which is a series of complex calculations across multiple layers. Depending on the configuration of the overlay, the {{#if:<noinclude>main</noinclude>|{{inlink|Calculation time impacts|calculation time}}|[[Water Overlay#Calculation time impacts|calculation time]]}} can range from seconds to hours. If the overlay is to be used in a setting where response times need to be short, it may be preferable to configure the overlay for greater speed rather than excessive precision.<!--
 
-->|}}</onlyinclude>
 
==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|lcase=1|Data}} which can be configured, along with the most important {{inlink|lcase=1|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 step for configuring a {{inlink|lcase=1|Breach}} area is included 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. Its various components can be configured in the following order:
: '''Breach''' ([[Flooding_(Overlay)|flooding overlays]] only): A {{inlink|lcase=1|Breach}}, a location where an (uncontrolled) inflow of water takes places.
: '''Water areas''': {{inlink|Water level area}}s, defined regions in which a specific water level is maintained. 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 sewers exist. 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 form of inundated land. It is also possible to have the wizard generate a single inundation area covering the entire project area.
: '''Aquifer areas''' ([[Groundwater_(Overlay)|groundwater overlays]] only): {{inlink|Aquifer|Aquifer area}}s, definitions for transmissivity or hydraulic conductivity of the underground layer.
 
: '''Weirs''': {{inlink|Weir}}s, minor barriers in the water flow.
: '''Culverts''': {{inlink|Culvert}}s, tunnels which form direct connections between two locations.
: '''Pumps''': {{inlink|Pump}}s, structures which move water from a lower to a higher location.
: '''Inlets''': {{inlink|Inlet}}s, structures which add or remove water.
: '''Sewer overflows''': {{inlink|Sewer overflow}}s, points where water from sewers can flow back onto the surface.
 
All of the above components 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|lcase=1|Terrain}} and {{inlink|Miscellaneous hydrological properties of constructions|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|lcase=1|Terrain}}s, attributes can be adjusted directly.
: '''Underground terrain''': For the underground {{inlink|lcase=1|Terrain}}s, attributes can be adjusted directly as well.
: '''Constructions''': For {{inlink|Miscellaneous hydrological properties of constructions|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|lcase=1|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|lcase=1|Result type}}s are available. 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|lcase=1|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 {{inlink|lcase=1|Input overlay}}s as well. These add [[Average Overlay]]s configured for the geographical display of attribute values relevant for the calculation of the water model.
 
===Manual configuration===
Besides using the configuration wizard, it is also possible to configure a number of settings manually. A few settings can only be changed manually. Besides the [[Data|data]] of geographical features, which have their own means of loading in depending on their type, all manual configuration options are listed here.
 
====Grid cell size configuration====
{{main|Grid overlay#Shared settings|Grid overlay}}
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=General tab|Change grid}}
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.
 
====Calculation preference configuration====
{{main|section=section|Calculation preference formula}}
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=General tab|Calculation preference}}
The calculation preference indicates the level of accuracy the calculations should be performed with. Depending on the configuration timesteps will be calculated more conservatively. This affects the time it takes to perform the full calculation, and the exact quantities of water moving between cells.
 
The calculation preference can be changed by selecting a different setting.
 
====Weather configuration (simulation time, rainfall, evaporation)====
{{main|section=section|Weather}}
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=Keys tab|"Edit", next to weather}}
The weather configuration, which dictates the {{inlink|Rain and simulation time|duration of the simulation, the amount of rain}} and the {{inlink|lcase=1|Evaporation rate}}, is modeled as a separate weather object which is connected to the water overlay. The weather object can be replaced with another, changing the main simulation and weather properties. The weather itself can be changed as well.
 
By selecting the weather object and then switching to the "Simulation" tab, it's possible to change the settings of the weather either for a simple linear setup or with a more complex sequence of values for the duration of the simulation. The complex setup can be created by loading in a [[comma-separated values]] file. By switching to the attributes tab of the weather object, the same properties can be adjusted by directly modifying the attributes.
 
====Ground water configuration====
{{main|section=section|Ground water data model|Ground water}}
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=Keys tab|Include ground water tiff}}
A ground water [[GeoTIFF]] can be loaded in to prepopulate the underground with water in the form of a saturated zone. This is only a relevant configuration when the {{inlink|lcase=1|Underground model}} is active. A ground water GeoTIFF is optional. If no ground water tiff is selected, the assumed ground water level is equal to the {{inlink|WATER_LEVEL}} of the {{inlink|lcase=1|Water level area}}.
 
The presence of a ground water GeoTIFF can be toggled by checking or unchecking the "Include ground water tiff" checkbox. When checked, a number of GeoTIFFs are available for ground water levels by default. Other GeoTIFFs for groundwater levels can also be loaded in by clicking on "Select GeoTiff".
 
====Subsidence configuration====
{{main|section=section|Subsidence data model|Subsidence}}
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=Keys tab|Include subsidence}}
It's possible to connect the water overlay to a [[Subsidence (Overlay)|subsidence overlay]], if one exists in the project. The result of the subsidence calculation, specifically the amount the terrain has lowered, are applied to the terrain height at the start of the water model's simulation. A connection to a subsidence overlay is optional. If no subsidence overlay is connected, the terrain height is not adjusted in this fashion.
 
The connection to a subsidence overlay can be made by changing the value selected in the "Subsidence" dropdown to the appropriate subsidence overlay.
 
====Showing system visualization setting====
{{main|section=section|System visualization|System visualization}}
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=General tab|Show system visualization}}
The water overlay performs a simulation in which much detailed flow takes place, but in which a number of features perform special functions related to water flow. These features include the sewers and the {{inlink|lcase=1|Hydrological constructions}}. The flow of these sections of the hydrological model can be visualized as an explicit graph overlayed on the overlay.
 
The system visualization can be toggled by checking or unchecking the "Show System Visualization" checkbox.
 
====Active in simulation setting====
{{main|Grid overlay#Active|Grid overlay}}
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=General tab|Active in simulation}}
Like all grid overlays, the water overlays can be configured to either an active or inactive state. This is especially useful when the results of a calculation should be available for insight without the computational overhead of always recalculating the overlay when changes in the project take place.
 
An overlay can be toggled between active and inactive by checking or unchecking the "Active in simulation" checkbox.
 
====Result type configuration====
{{main|section=section|Result type}}
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=General tab|Result type}}
The water model performs a complete simulation in which water flows through the project area. For many use-cases only a specific type of output resulting from the simulation is relevant. The result type of the water overlay indicates exactly what kind of data is recorded and outputted.
 
The result type can be changed by selecting the desired result type in the "Result type" dropdown.
 
Note that via the {{inlink|lcase=1|Configuration wizard}} multiple result types can be added in parallel in the form of {{inlink|lcase=1|Result child overlays}}.
 
====Legend configuration====
{{main|Grid overlay#Legend|Grid overlay}}
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=Legend tab}}
Depending on the selected {{inlink|lcase=1|Result type|}}, the output created by the water overlay can or should be interpreted in different ways. The raw data calculated is assigned colors based on the configured legend. Each result type has an assigned default legend which helps with interpreting the output. The default legends will often be sufficient, but can be modified to fit specific meanings or result ranges.
 
The legend can be modified in the "Legend" tab by checking the "Has custom legend" checkbox. Entries for the legend can then be added, modified, and removed. Any changes in the legend are applied to the visualization immediately, without recalculation of the overlay's output values.
 
====Keys configuration====
{{main|section=section|Keys}}
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=Keys tab}}
The water model's calculations rely on a number of [[area]]s and [[construction]]s for their input data. {{inlink|Hydrological features}} and {{inlink|lcase=1|Hydrological constructions}} have special meanings in terms of policy or scenario. To allow for both compatibility with external data as well as parallel calculations for different scenario's, it is possible to (re)define the exact attributes the overlay uses for those inputs. This would allow two instances of a water overlay to work with the same dataset but with different configurations for hydrological features or constructions.
 
The exact attributes the overlay uses as input from hydrological features and constructions can be changed on the "Keys" tab, by using the relevant dropdown to change the attribute name to the desired attribute.
 
====Attributes configuration====
{{main|section=section|Attributes}}
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=Attributes tab}}
The water model's calculations make use of a number of centralized parameters, which are configured as [[attribute]]s of the overlay. Depending on the exact {{inlink|lcase=1|Variants}} of the water overlay, some of the parameters will have different defaults to better suit the exact type of calculation. The parameters can be tweaked further to better fit specific use-cases, but in general the defaults are appropriate for most calculations.
 
Any of the attributes of the overlay can be changed on the "Attributes" tab, by changing the value in the input box for the attribute which is to be changed.
 
==Results==
When the calculation completes, the results are stored as numerical values in a grid spanning the entire [[3D world]]. The exact values and their meanings depend on the selected {{inlink|lcase=1|Result type}}. Each {{inlink|Timeframes|timeframe}} and each {{inlink|lcase=1|Result child overlays}} has it's own grid of data. There are multiple ways to interact with this data. In addition, there are a few additional outputs provided by the water overlay specifically to gain further insight, verification, and visualization of the results.
 
===Geographical overview===
The most common method of analyzing the results of the calculation is by performing a simple visual inspection of the values of the grid. A basic visual overview along with the ability to select a specific location for further information can suffice for most initial result analysis.
 
====Visualization====
The results of the calculation are visualized when the overlay is selected, based on the colors configured for the overlay's [[Grid overlay#Legend|legend]]. Each location in the [[3D world]] is displayed using a color either matching a value as configured in the legend, or an interpolation of colors between the colors of two values. This means a grid of numerical values, which would be difficult to inspect at a glance, can instead be viewed intuitively.
 
====System visualization====
Depending on whether the option is selected, the hydrological system can be visualized when when the overlay is activated. Each {{inlink|lcase=1|Water level area}} will be visualized by a blue floating sphere and a striped border along the surface of the terrain. {{inlink|Sewer area}}s are visualized by an orange floating sphere. If the sewer has a {{inlink|lcase=1|Sewer overflow}}, the overflow is connected to the sewer's sphere via an orange line. {{inlink|Hydrological constructions|Culverts, weirs, and pumps}} are visualized by green, orange, and red spheres respectively for their endpoints, connected by blue lines.
 
If water has flowed through any of the {{inlink|lcase=1|Hydrological constructions}}, animated arrows in the connecting lines will indicate that movement.
 
====Hover panel====
When the overlay is selected, it's possible to click anywhere in the 3D world to open the [[hover panel]]. This panel shows some information about the clicked location. The following information is displayed by the hover panel:
* The ground height, which is the {{inlink|Terrain height|terrain height}} relative to {{datum}}.
* The output value of the overlay, which is dependent on the selected {{inlink|Result type|result type}}.
* The hydrological properties of the terrain (if applicable), such as {{inlink|WATER_MANNING|manning value}} and {{inlink|GROUND_INFILTRATION_MD_surface|infiltration speed}}.
* The hydrological properties of features (if applicable), such as {{inlink|WATER_LEVEL|water level}}, {{inlink|INUNDATION_LEVEL|inundation level}}, and {{inlink|BREACH_HEIGHT|altered terrain height}}.
* The hydrological properties of constructions (if applicable), such as {{inlink|WATER_STORAGE|building storage}}, and {{inlink|SEWER_STORAGE|sewer storage}} of {{inlink|SEWERED|sewered buildings}}.
 
===Detailed results===
After a first visual inspection of the output, there are several means of gaining a more detailed insight into the results. Several built-in tools allow for a more intuitive way of reading and comparing results, while there are also means available to use the results for further programmatic analyses.
 
====Timeframes====
The water overlay can be configured to store multiple {{inlink|TIMEFRAMES|timeframes}} of results. Each timeframe is a complete snapshot of results of the entire project area. These results can be viewed in sequence for an intuitive overview of the progression of the simulation. By clicking on the "play" button in the [[session interface#Legend|legend in the session interface]], an animation is started which displays the timeframes in sequence.
 
Note that the simulation time is divided into a {{inlink|TIMEFRAMES}} amount of periods, and at the end of each period a timeframe is recorded. This means the first timeframe is not a snapshot of the initial state of the simulation, but a snapshow of the state of the simulation after the first period of time has passed already.
 
====TQL====
{{main|TQL}}
The overlay's data can be computationally retrieved using TQL. This allows the results of the overlay to be summarized, and to be used in the calculations of [[excel]]s for the use in [[indicator]]s or [[panel]]s.
 
====Measuring tool====
{{main|Measuring tool}}
While viewing the overlay, a general impression of the values can be seen at a glance. However, depending on the configuration of the overlay's [[Grid overlay#Legend|legend]] the exact values may be difficult to view exactly. Using the measuring tool it's possible to retrieve the values of the overlay on exact locations. Additionally, cross-sections can be defined and easily have their values inspected.
 
====Exporting Geotiff====
{{main|Grid overlay#Export|Grid overlay}}
The [[3D client]] offers sufficient ways to visually inspect the water overlay's results for general overview, but use-cases exist in which post-calculation analysis in external tools is desirable. For these situations it is possible to export the results of the calculation in the form of a [[GeoTIFF]]. The resulting file can be opened in other GIS software.
 
===Additional forms of output===
A number of output forms don't fit in the analysis structure described above, but can provide additional information or insight into the calculation. These can provide different ways of looking at both the input and output of the simulation. They are offered as a means to further visualize but also verify the performed calculations.
 
====Weather visualization====
When a water overlay exists in a project, and the animation of a [[weather]] is triggered (either manually or automatically), the animation of the weather will include a visualization of the water as it progresses during the simulation.
 
During the weather animation, panels which make use of the [[Panel#VISIBLE_TIMEFRAME|VISIBLE_TIMEFRAME]] attribute will appear only from the specified {{inlink|Timeframes|timeframe}}.
 
In a setup where only a single water overlay refers to a weather effect, when that weather effect is triggered that water overlay's simulation is animated. When multiple water overlays or no water overlay refer to a weather effect, the behavior for visualization is not consistently defined, and a water overlay will be semi-randomly selected for visualization.
 
====Saving overlay result====
{{main|Grid overlay#Save|Grid overlay}}
When a water overlay has completed a complex calculation, it may be interesting to save the results as an inactive copy. This will create a duplicate overlay configured exactly the same way as the original, but set to be [[Grid overlay#Active|inactive]]. This will allow the current results to be kept available as a separate overlay without additional computational overhead, and for the original overlay to be used for further calculations of other scenario's.
 
====Water balance====
[[File:water_balance.jpg|thumb|250px|A water balance with multiple input and output entries.]]
 
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=General tab|Show water balance}}
 
During the simulation, a tally is kept of the total amount of water which the hydrological model is initialized with, how much flows in and out, and how much is left in various layers when the simulation completes. The overview of these tallies is known as the water balance, and can be accessed after the calculation has completed. It will display water categorized into input (where it was initialized and/or how it entered the hydrological system) and output (where in the hydrological system it ended up, or through which path or process it left the hydrological system).
 
The following entries are displayed:
{|class='wikitable'
! Input
! Output
|-
| style="vertical-align:top"|
* Breach
* Inlet
* Rain
* Water surface
* Inundated land
| style="vertical-align:top"|
* Breach out
* Outlet
* Land surface
* Water surface
* Building surface
* Sewer storage
* Underground unsaturated storage
* Underground saturated storage
* Evaporated
|}
For completeness, a total for both water input and output is displayed, as well as a check on any eventual water loss in the system. Depending on the size of the project area and the amount of water flowing through various cells, there may be a minor difference between the input and output due to numerical rounding. In these cases the difference should amount to less than a tenth of a millimeter of water per cell in the calculation.
{{clear}}
 
====Debug info====
[[File:debug_info.jpg|thumb|250px|Debug information as generated by a calculation of the Water Overlay.]]
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=General tab|Debug info}}
 
After the calculation completes, some additional information is tallied and output for debugging purposes. This is intended for verification that the model has computed as expected, and may provide some basic information at a glance. It is not meant as a primary tool for in-depth analysis of the results.
 
The following information is displayed:
{|class='wikitable'
! Debug info
|-
| style="vertical-align:top"|
* Total rainfall
* Simulation time (and amount of timeframes)
* Map size
* Amount of cells and amount of {{inlink|Timestep formula|computational timesteps}}
* Amount of special hydrological areas
* Amount of flow over weirs
* Amount of overflow from sewers
* Total calculation time, and the amount of [[GPU]]'s used to perform the calculation
* Total volume of water processed
|}
 
====Input overlay====
{{main|Average Overlay}}
The water overlay's calculations rely on multiple geographical parameters, such as {{inlink|WATER_MANING|manning value}}s and {{inlink|WATER_EVAPORATION_FACTOR_surface|evaporation factors}}. To help with both understanding the outcome of the calculation as well as verifying the results, the {{inlink|Configuration wizard|configuration wizard}} offers the option to add input overlays to the project, which are [[Average Overlay]]s configured to display the input parameters geographically.
 
Overlays such as these can also be created manually, by creating an Average Overlay and configuring it such that it functions on the desired [[attribute]], and with an as small an averaging distance as possible. Optionally, a specific layer (such as [[construction]]s or [[terrain]]s) can be configured which the overlay should inspect.
 
==Model connections==
The hydrological model can be linked to other models, which adds and defines more data for the simulation. Some models are automatically connected, and are required for the calculations to take place. Others are optional, and can apply additional detail to the calculations. When the optional models are absent, default behavior is defined.
 
===Terrain height===
{{main|Terrain height}}
Terrain height in the {{software}} 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=Terrain height
|description=The height of the terrain's surface across the project area.
|nodata=Data is unchanged from the base terrain height.
|value=Terrain height
|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) 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
|[[File:Overlay_flooding.png]]
|minutes
|[[Flooding_(Overlay)|Flooding Overlay]]
|How long rain should last at the start of the simulation.
|provides insight into water stress and impact caused by breaches in levees or other sources causing excessive water inflow
|-
|-
|Total rainfall
||[[File:Overlay_groundwater.png]]
|mm
|[[Groundwater_(Overlay)|Groundwater Overlay]]
|How much rain should fall in the specified period.
|provides insight into long-term processes of water flow both on the surface and underground
|-
|Dry after rain (days, hours, minutes)
|days, hours, minutes
|How long the simulation continues after the rain has fallen.
|}
|}
<!--==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 rate====
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===
==Results==
Ground water in the {{software}} is modeled in the form of a [[GeoTIFF]].
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]].


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.
==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)


Ground water is only a relevant connection when the {{inlink|lcase=1|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.
===Features and components===
 
* [[Hydrological features (Water Overlay)|Hydrological features]]
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|lcase=1|Water level area}}s.
* [[Hydraulic structures (Water Overlay)|Hydraulic structures]]
 
* [[How to_manually_configure_a_Water_Overlay|Manual configuration Options]]
{{GeoTIFFSpec
* [[Simulation data (Water Overlay)|Simulation data]]
|title=Groundwater
|description=The height of the ground water level across the project area.
|value=Groundwater level
|unit=m below terrain height
}}
 
===Subsidence===
{{main|Subsidence (Overlay)}}
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|lcase=1|Breach}}es, still apply.
 
==Data==
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.
 
===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|lcase=1|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 water will flow in from the simulated external water body.. 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 through the breach and its simulated water body does not "count" for the critical speed. All cells in the active breach are considered directly adjacent to the external water body.
 
The entire breach area is considered lowered to the height defined by its {{inlink|BREACH_HEIGHT}} attribute, even if the active breach does not extend across the entirety of the breach area.
 
Water flowing through or across a breach will flow in the direction defined by the {{inlink|BREACH_ANGLE}} attribute, regardless of whether the water flowed onto the breach from elsewhere in the water model, or from the simulated external water body. If no {{inlink|BREACH_ANGLE}} is defined, water can flow in any direction.
 
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_ANGLE|BREACH_ANGLE}}
|{{geoangle}}
|The angle at which water can flow from the breach.
|n/a
|-
|{{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|lcase=1|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
|}
 
====Aquifer====
The aquifer is an additional definition for the underground, allowing for {{inlink|Underground model|underground horizontal flow}} different from the underground terrain's {{inlink|GROUND_INFILTRATION_MD_underground|GROUND_INFILTRATION_MD}}.{{RequestImage|description=Wide Depiction of underground terrain. Part of the underground has 1 or 2 arrows to depict flowing right. A part further right is highlighted (the aquifer) and has 3 or 4 arrows depicting flow to the right.}}
{| class="wikitable"
! Attribute
! Unit
! Description
! Default (when attribute is not present)
|-
|{{anchor|AQUIFER_KD|AQUIFER_KD}}
|m²/day
|The hydraulic conductivity of the aquifer, which dictates the speed at which water can flow horizontally through the underground.
|n/a
|-
|{{anchor|AQUIFER_HEIGHT|AQUIFER_HEIGHT}}
|m
|
|n/a
|}
Note that the aquifer only functions if its hydraulic conductivity is greater than 0. If it is 0 or less the aquifer is disregarded, and the {{inlink|GROUND_INFILTRATION_MD_underground|GROUND_INFILTRATION_MD}} of the underground terrain is used.
 
===Hydraulic stuctures===
See [[Hydraulic structures]] for the list of supported structures.
 
===Additional hydrological attributes of constructions===
Besides the [[construction]]s which directly influence the main water flow in the hydrological model, each construction 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 hydrological structure attributes, which are stored and used on an object level in the water model.
 
These attributes can be changed individually per construction or per construction's function. In most cases, these attributes already exist as a [[function values|function value]]. Note that attributes which are connected to a function value can not be redefined using a different attribute name.
 
For a full list, see [[Additional_hydrological_attributes_of_constructions_(Water Overlay)|Additional hydrological attributes of constructions]].
 
===Hydrological properties of terrain===
[[Terrain]]s in a project have a number of hydrological properties 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 properties of terrains, unless a construction is present with overwriting values.
 
For a full list, see [[Terrain_attributes_(Water_Overlay)| Terrain attributes for the water overlay]].
 
==Settings==
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 complete simulation.
 
===Result type===
{{Editor ribbon|header=Current situation|bar=Overlays|left panel=The overlay|right panel=General tab}}
{{main|Result_type_(Water_Overlay)|Result types}}
 
===Keys===
The water model makes use of data present in geographical features in the [[3D world]]. This data is used as input for the various calculations which together model the water flow. The water model recognizes what attributes of geographical features form the parameters required for the calculation through key definitions. Each key is the name of an attribute which the water model should use to determine a specific parameter.
 
Keys are set to default attribute names, which apply to {{inlink|lcase=1|Hydrological features}}, {{inlink|lcase=1|Hydrological constructions}}, and {{inlink|lcase=1|Hydrological properties of terrain}}. Keys can be changed so that imported data can be interpreted without renaming attributes, or to allow different configurations to come forth from the same dataset.


===Attributes===
===Attributes===
{{main|Model_attributes_(Water_Overlay)|Water Model attributes}}
* [[Model attributes (Water Overlay)|Water Module Attributes]]
 
* [[Hydrological attributes of buildings (Water Overlay)|Hydrological Attributes of Buildings]]
==Calculations==
* [[Hydrological attributes of terrains (Water Overlay)|Hydrological Attributes of Terrains]]
The water overlay performs a large number of calculations to form a complete hydrological simulation. Depending on the desired viewpoint, both the overarching concepts as well as the implemented formulas can be reviewed for detailed insight into how the water overlay works.
 
===Models===
Multiple models are implemented which in conjunction form the water model in its entirety.
 
* [[Surface_model_(Water_Overlay)|Surface model]]
* [[Underground_model_(Water_Overlay)|Underground model]]
* [[Rain_model_(Water_Overlay)|Rain model]]
* [[Evaporation model (Water Overlay)|Evaporation model]]
* [[Sewer_model_(Water_Overlay)|Sewer model]]
* [[Storage_model_(Water_Overlay)| Storage model]]
* [[Chemical_flow_model_(Water_Overlay)|Chemical flow model]]
* [[Border_model_(Water_Overlay)|Border model]]
 
===Formulas===
The precise calculations which govern the water overlay's simulation are many and varied, and based as much as possible on available expert knowledge.
 
Model related Formula's:
* [[Timestep_formula_(Water_Overlay)|Timestep formula]]
* [[Calculation_preference_formula_(Water_Overlay)|Calculation preference formula]]
* [[Surface_water_level_formula_(Water_Overlay)|Surface water level formula]]
* [[Groundwater_level_formula_(Water_Overlay)|Groundwater level formula]]
* [[Surface_flow_formula_(Water_Overlay)|Surface flow formula]]
* [[Underground_flow_formula_(Water_Overlay)|Underground flow formula]]
* [[Surface_evaporation_formula_(Water_Overlay)|Surface evaporation formula]]
* [[Underground_evaporation_formula_(Water_Overlay)|Underground evaporation formula]]
* [[Surface_infiltration_formula_(Water_Overlay)|Surface infiltration formula]]
* [[Underground_infiltration_formula_(Water_Overlay)|Underground infiltration formula]]
 
Hydraulic structure related Formula's:
* [[Culvert_formula_(Water_Overlay)|Culvert formula]]
* [[Weir_formula_(Water_Overlay)|Weir formula]]
* [[Breach_growth_formula_(Water_Overlay)|Breach growth formula]]
* [[Breach_flow_formula_(Water_Overlay)|Breach flow formula]]
* [[Pump_formula_(Water_Overlay)|Pump formula]]
* [[Sewer_Overflow_formula_(Water_Overlay)|Sewer Overflow formula]]
* [[Inlet_formula_(Water_Overlay)|Inlet formula]]
 
===Computational structure===
{{stub|type=section}}
The formulas and concepts come together in a single computational structure which is repeated a large number of times until the total simulation duration has been reached.
 
====Order of operations====
During the calculation, multiple facets have to be calculated. In each timestep, each aspect of the calculation has to be performed. Although as timesteps become smaller exact order of operation becomes less important, the order of operations can lead to specific behavioral details in some edge cases.
 
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
* Hydrological constructions (culverts, weirs, pumps, in- and outlets, outlets)
* Hydrological areas (sewer overflow, breach in- and outflow)
* Chemical movement, based on the water flow and infiltration which has occurred
 
==Warnings and recommendations==
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.
 
===Configuration wizard warnings===
While configuring the water overlay using the {{inlink|lcase=1|Configuration wizard}}, each type of {{inlink|lcase=1|Data}} loaded in or found in the project must meet certain requirements to be functional. For example, configured {{inlink|WATER_LEVEL|water levels}} may deviate greatly from the mean terrain height in the project, or certain {{inlink|lcase=1|Hydrological constructions}} may not be shaped appropriately or intersect with required features. In these cases, the configuration wizard will show the warnings in the steps related to the specific type of data.
 
===Inaccurate terrain===
When the [[Terrain_height#Terrain_height_in_the_Tygron_Platform|project is created]], the advanced options allow for selecting a high-resolution height map to be loaded in. The default, low resolution height map can introduce artifacts in the calculation due to inaccuracy. This issue can currently only be resolved by reloading the project area.
 
===Calculation halted===
If the overlay is recalculated, but the [[Recalculate indicators|(re)calculation is halted]], the water overlay will not contain meaningful results. A warning will be displayed indicating that the calculation did not complete.
 
===Large cell size===
The water overlay performs its calculations based on a discretization of the project area. This means both that areas of water are considered a single block, and that obstacles and hydrological properties are averaged out over the extent of a cell. To best approach a realistic, continuous water flow and a realistic model of obstacles and values, it is sufficient to reduce the size of the cells the calculation uses.
 
===Limited cycles===
{{stub|type=section}}
 
====Calculation time impacts====
{{stub|type=section}}


<!--==References==
{{WaterOverlay output nav}}
<references>
{{Overlay nav}}
<ref name="hydradius">DUFLOW manual ∙ found at: http://resolver.tudelft.nl/uuid:97184101-cc3b-483a-bba0-3d2bfdf31cdd ∙ (last visited 2019-03-08)</ref>


</references>-->
[[Category:Water Module]][[Category:Overlays with result types]]

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.

Overlay rainfall.png Rainfall Overlay provides insight into the water stress and impact caused by (excessive) rainfall
Overlay flooding.png Flooding Overlay provides insight into water stress and impact caused by breaches in levees or other sources causing excessive water inflow
Overlay groundwater.png 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