Water Overlay

What is the Water overlay

The water 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.

Water flow is affected by properties of the surface across which it flows, including the terrain height and the properties of the underlying terrain.

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, 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.

The final results of the calculation can be inspected, as well as snapshots of the hydrological situation in the simulation, known as 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, provides insight into the water stress caused by (excessive) rainfall.
• Flooding Overlay, provides insight into water stress 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.

Use cases

Main article: Use cases Water Overlay

This section is a stub.

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 water overlay's use cases page.

How to use the Water overlay

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 prerequisites. Next, it is recommended to prepare all 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 climate conditions and what kind of output is desired. After these preparations have been made, creation and configuration of the overlay can begin. When the configuration is completed, a recalculation of the overlay will yield more accurate and appropriate results.

After the overlay has calculated results, a number of means exist to analyse the results of the calculation performed.

Prerequisites

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 new project wizard.
• Your project is large enough to account for edge effects.

Additional tips for preparation and use

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 new project wizard, consider using the 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 IMWA dataset for hydrological constructions. Although this dataset is not complete, some information about constructions which serve as culverts 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 levees. To have these small features included properly in the calculations, the grid cell size will need to be set to an appropriate size. The default setting offered by the Tygron Platform 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 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.

Configuration

See: Water Overlay Configuration

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 result type. Each timeframe and each 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 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 water level area will be visualized by a blue floating sphere and a striped border along the surface of the terrain. Sewer areas are visualized by an orange floating sphere. If the sewer has a sewer overflow, the overflow is connected to the sewer's sphere via an orange line. 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 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 terrain height relative to datum.
• The output value of the overlay, which is dependent on the selected result type.
• The hydrological properties of the terrain (if applicable), such as manning value and infiltration speed.
• The hydrological properties of features (if applicable), such as water level, inundation level, and altered terrain height.
• The hydrological properties of constructions (if applicable), such as building storage, and sewer storage of 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 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 legend in the session interface, an animation is started which displays the timeframes in sequence.

Note that the simulation time is divided into a 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 article: 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 excels for the use in indicators or panels.

Measuring tool

Main article: 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 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 article: 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 VISIBLE_TIMEFRAME attribute will appear only from the specified 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 article: 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 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

A water balance with multiple input and output entries.

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:

Input	Output
Breach Inlet Rain Water surface Inundated land	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.

Debug info

Debug information as generated by a calculation of the Water Overlay.

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:

Debug info
Total rainfall Simulation time (and amount of timeframes) Map size Amount of cells and amount of 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 article: Average Overlay

The water overlay's calculations rely on multiple geographical parameters, such as manning values and evaporation factors. To help with both understanding the outcome of the calculation as well as verifying the results, the configuration wizard offers the option to add input overlays to the project, which are Average Overlays 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 constructions or terrains) 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 article: Terrain height

Terrain height in the Tygron Platform 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.

Weather

Weather in the Tygron Platform is modeled in the form of a 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
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.

Property	Unit	Description
Rain for	minutes	How long rain should last at the start of the simulation.
Total rainfall	mm	How much rain should fall in the specified period.
Dry after rain (days, hours, minutes)	days, hours, minutes	How long the simulation continues after the rain has fallen.

Custom configuration
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.

Rain and simulation CSV specification
Data per line	Additional rainfall until specified moment
Criteria	Time should always be greater than or equal to previous time Rain should never be negative
	First entry	Second entry
	Time (s)	Rain (m)
Line 1	Time when first period ends	Total rain during first period
Line 2	Time when second period ends	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 evaporation model.

Linear configuration
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.

Property	Unit	Description
Surface evaporation	mm/day	The speed at which water evaporates during the simulation

Custom configuration
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.

Evaporation CSV specification
Data per line	Rate of evaporation until specified moment
Criteria	Time should always be greater than or equal to previous time Evaporation should never be negative
	First entry	Second entry
	Time (s)	Evaporation (m)
Line 1	Time when first period ends	Amount of evaporation during first period
Line 2	Time when second period ends	Amount of evaporation during second period

Ground water

Ground water in the Tygron Platform is modeled in the form of a GeoTIFF.

The hydrological model can simulate the 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 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 water level areas.

Subsidence

Main article: Subsidence (Overlay)

Subsidence in the Tygron Platform is modeled in the form of a subsidence overlay.

The hydrological model is greatly influenced by the 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 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 breaches, 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, constructions 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 areas. These hydrological features form special properties or modifications on the hydrological system.

See Hydological features.

Hydraulic stuctures

See Hydraulic structures for the list of supported structures.

Additional hydrological attributes of constructions

Besides the constructions 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 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.

Hydrological properties of terrain

Terrains 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 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

Main article: 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 hydrological features, hydrological constructions, and 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

Main article: Water Model attributes

Calculations

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
• Underground model
• Rain model
• Evaporation model
• Sewer model
• Storage model
• Chemical flow model
• 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
• Calculation preference formula
• Surface water level formula
• Groundwater level formula
• Surface flow formula
• Underground flow formula
• Surface evaporation formula
• Underground evaporation formula
• Surface infiltration formula
• Underground infiltration formula

Hydraulic structure related Formula's:

• Culvert formula
• Weir formula
• Breach growth formula
• Breach flow formula
• Pump formula
• Sewer Overflow formula
• Inlet formula

Computational structure

This section is a stub.

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 configuration wizard, each type of data loaded in or found in the project must meet certain requirements to be functional. For example, configured water levels may deviate greatly from the mean terrain height in the project, or certain 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 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 (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

This section is a stub.

Calculation time impacts

This section is a stub.