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

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

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 data which can be configured, along with the most important attributes of the overlay.

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 overlays a step for configuring a 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 weather event defines the total simulation time and the weather and climate effects during the simulation. Specifically, the amount of rain and when it falls during the simulation, as well as the evaporation which takes place.

Step 2: Water system

The water system is the most complex step of the configuration, and contains a multitude of substeps to configure all geographical data. In order, the following data can be configured:

Breach (flooding overlays only): A breach, a location where an (uncontrolled) inflow of water takes places, can be imported or connected to the hydrological model.

Water areas: Water level areas, defined regions in which a specific water level is maintained, can be imported or connected to the hydrological model. It is also possible to have the wizard generate a single water level area for the entire project area.

Ground water: Ground water, the height of the underground saturated by water, relative to datum. A GeoTIFF can be imported.

Sewers: Sewer areas, the broad definitions for where what kind of sewers exist, can be imported or connected to the hydrological model. It is also possible to have the wizard generate sewer areas based on the neighborhoods in the project area.

Inundation areas: Inundation areas, definitions of water on the surface, in the forum of inundated land, can be imported or connected to the hydrological model. It is also possible to have the wizard generate a single inundation area covering the entire project area.

Aquifer areas (groundwater overlays only): Aquifer areas, definitions for transmissivity or hydraulic conductivity of the underground layer, can be imported or connected to the hydrological model.

Weirs: Weirs, minor barriers in the water flow, can be imported or connected to the hydrological model.

Culverts: Culverts, tunnels which form direct connections between two locations, can be imported or connected to the hydrological model.

Pumps: Pumps, structures which move water from a lower to a higher location, can be imported or connected to the hydrological model.

Inlets: Inlets, structures which add or remove water, can be imported or connected to the hydrological model.

Sewer overflows: Sewer overflows, points where water from sewers can flow back onto the surface, can be imported or connected to the hydrological model.

Step 3: Hydrological coefficients

Hydrological coefficients are values of existing elements of the world, specifically terrain and 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 terrains, attributes can be adjusted directly.

Underground terrain: For the underground terrains, attributes can be adjusted directly as well.

Constructions: For 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 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.

Step 5: Output overlays

Multiple result types 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 result child overlays. Relevant attributes can be modified as well, if they are related to selected result types.

Finally, the TIMEFRAMES attribute can be configured here as well, defining the amount of result snapshots which should be made during the calculation.

Step 6: Input overlays

To gain more insight into the data used by the model, you may opt to add one or more input overlays as well. These add Average Overlays 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 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 article: Grid overlay

Template:Editor ribbon 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: Calculation preference formula

Template:Editor ribbon 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: Weather

Template:Editor ribbon The weather configuration, which dictates the duration of the simulation, the amount of rain and the 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: Ground water

Template:Editor ribbon 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 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 WATER_LEVEL of the 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: Subsidence

Template:Editor ribbon It's possible to connect the water overlay to a 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: System visualization

Template:Editor ribbon 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 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 article: Grid overlay

Template:Editor ribbon 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: Result type

Template:Editor ribbon 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 configuration wizard multiple result types can be added in parallel in the form of result child overlays.

Legend configuration

Main article: Grid overlay

Template:Editor ribbon Depending on the selected 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: Keys

Template:Editor ribbon The water model's calculations rely on a number of areas and constructions for their input data. Hydrological features and 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: Attributes

Template:Editor ribbon The water model's calculations make use of a number of centralized parameters, which are configured as attributes of the overlay. Depending on the exact 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 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.

Water level area

A water level area represents real-world water level areas. Within a water level area, the heights of all water terrains are set to a specified level.

Attribute	Unit	Description	Default (when attribute is not present)
WATER_LEVEL	m + datum	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 sewered construction.

Attribute	Unit	Description	Default (when attribute is not present)
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
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 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 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 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 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 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 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 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.

Attribute	Unit	Description	Default (when attribute is not present)
BREACH_HEIGHT	m + datum	The new terrain height at the location of the breach.	n/a
BREACH_WIDTH	m	The radius of the breach as drawn on the polygon defining the breach, emanating from the center point.	10000
BREACH_ANGLE	angle (0-90°)	The angle at which water can flow from the breach.	n/a
BREACH_SPEED	m/s	The speed at which water should flow through the breach before the width begins to increase.	n/a
EXTERNAL_SURFACE_LEVEL	m + datum	The height of the bottom of the external water body behind the breach. The lowest level the external water level can lower to.	0
EXTERNAL_WATER_LEVEL	m + datum	The water level of the external water body behind the breach. The initial level the water level is set to.	0
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 water level areas in that an inundation level allows you to place water anywhere on the surface.

Attribute	Unit	Description	Default (when attribute is not present)
INUNDATION_LEVEL	m + datum	The height of the water.	n/a

Aquifer

The aquifer is an additional definition for the underground, allowing for underground horizontal flow different from the underground terrain's GROUND_INFILTRATION_MD.

Attribute	Unit	Description	Default (when attribute is not present)
AQUIFER_KD	m²/day	The hydraulic diffusivity of the aquifer, which dictates the speed at which water can flow horizontally through the underground.	n/a
AQUIFER_HEIGHT	m		n/a

Note that the aquifer only functions if its diffusivity is greater than 0. If it is 0 or less the aquifer is disregarded, and the GROUND_INFILTRATION_MD of the underground terrain is used.

Hydrological constructions

The water system can be enhanced with a number of hydrological constructions. These are constructions which effect water flow in specific cells, according to the parameters and rules of the constructions used. The effects of these constructions can be adjusted by setting the appropriate attributes.

In general, hydrological constructions are loaded in as underground constructions.

Hydrological constructions can be either line-based or point-based:

• Line-based constructions
  Line-based constructions form a direct connection between two exact cells, allowing water to flow from one point to another. The flow is dictated by the construction's formula. The endpoints of a line-based construction, the exact cells which are connected by the construction, are computed based on the orientation and size of their polygon. Essentially, the furthest ends of the polygon are used as end-points. Because the cells are considered adjacent, any calculated flow through line-based hydrological constructions is instantaneous.
• Point-based constructions
  Point-based constructions add or remove water in one or more computational layers, based on their formula's. The centerpoint of a point-based construction, the exact cell where the effect takes place, is is the geometric center of the construction's polygon.

Note that the more complex the polygon is, the more difficult it is for the Tygron Platform to resolve it to a simple line or center point.

When the calculation of the water overlay completes, the total amount of water which has flowed through a specific construction is stored in an attribute in that construction. By default, this attribute is OBJECT_OUTPUT_FLOW, and the flow is expressed in m3. If multiple water overlays exist in the project simultaneously, the attribute name is appended with a number so that each overlay (as they are added to the project) has a unique attribute it writes its results to.

Hydrological constructions can only function as a single hydrological construction. If a single construction has attributes related to multiple hydrological constructions, the resulting behavior is undefined.

Culvert

Culverts are effectively tunnels or pipes directly connecting two bodies of water, and allow water to flow in either direction. Culverts can also be used to model tunnels on land, creating a hole which water can flow through when it is flowing over land. The throughput of a culvert is limited by its dimensions.

Culverts are assumed to have a spherical cross-section.

A culvert is a line-based constructions.

Attribute	Unit	Description	Default
CULVERT_DIAMETER	m	The diameter of the culvert. For throughput calculations, the culvert is assumed to have a spherical cross-section.	1
CULVERT_THRESHOLD	m + datum	The height of the culvert. (When set to a level lower than the terrain for either endpoint of it, the culvert's height is equal to the height of the (highest) terrain under either endpoint.)	0
CULVERT_N	manning value	The manning value of the culvert's material, which influences the flow speed.	0,014

Weir

Weirs are effectively small dams in the water, and allow water to flow from a water body with a higher water level to a lower water level. Any water exceeding the height of the weir can flow over it, increasing the throughput as the water level increases. Strictly, water can flow over the weir in either direction.

A weir is a line-based constructions.

Attribute	Unit	Description	Default
WEIR_HEIGHT	m + datum	The height of the weir.	n/a
WEIR_WIDTH	m	The width of the weir.	5
WEIR_COEFFICIENT	coefficient	The flow coefficient related to the shape of the weir.	1,1

Pump

Pumps are constructions which can move water against its natural flow. Specifically, it moves water from the lower end of the pump to the higher end of the pump. The terrain height is used to determine the low end and the high end of the pump.

A pump is a line-based constructions.

Attribute	Unit	Description	Default
PUMP_SPEED	m3/s	The speed at which water is pumped from the lower end-point to the higher end-point.	n/a

If a pump is placed such that both end-points are at locations with equal terrain height, the pump will be inactive and no water will flow through it.

Sewer overflow

Sewer overflows are points where water is moved from the sewer area to the above-ground water system. A sewer overflow will allow water to flow through if the water in the sewer exceeds the SEWER_OVERFLOW_THRESHOLD, and the water in the connected sewer exceeds the height of the terrain at the location of the sewer overflow. It will then function for all sewers part of that sewer area.

A sewer overflow is a point-based constructions. It must intersect with a sewer area, but does not need to intersect with a an actual sewer.

Attribute	Unit	Description	Default
SEWER_OVERFLOW	m + datum	The height of the bottom of the sewer, relative to the average terrain height of the connected sewer. Starting from this height, the water height in the sewer must exceed the height of the terrain at the location of the overflow in order for water to flow out.	n/a
SEWER_OVERFLOW_SPEED	m3/s	The maximum speed at which water can flow out from the sewer through this overflow.	10

Note that at most one overflow can exist per sewer area.

Inlet

Inlets are points where water is either added to or removed from the hydrological model. It will add or remove water at a defined maximum rate, with optional thresholds for the amount of water to add or remove.

An inlet is a point-based constructions.

Attribute	Unit	Description	Default
INLET_Q	m3/sec	The maximum amount of water flowing into the model through this inlet. A negative value means the construction functions as an outlet, and water is removed from the hydrological model.	Infinite
INLET_CAPACITY	m3	The maximum amount of water which can flow in or out through this construction. Water flowing back in the other direction replenishes the capacity.	Infinite
LOWER_THRESHOLD	m + datum	If a lower threshold is set, water will only flow into the model through this inlet until the water level at the point of this inlet is equal to or greater than the threshold. If the threshold is not set, the amount of water flowing in is not limited in this fashion.	None
UPPER_THRESHOLD	m + datum	If an upper threshold is set, water will only flow out the model through this outlet until the water level at the point of this inlet is equal to or lower than the threshold. If the threshold is not set, the amount of water flowing out is not limited in this fashion.	None

Note that all inlet attributes function as flow limits. If multiple are defined, water can flow in or out up until any of those limits are reached. If none are defined, no water flows in or out.

Miscellaneous hydrological properties of constructions

Besides the constructions which directly influence the main water flow in the hydrological model, all constructions have properties which may interact with the hydrological model in some way.

The effects of these constructions can be adjusted by setting the appropriate attributes. In some cases, these are attributes which relate to function values. For these attributes, either can be adjusted to the same effect. Note that attributes which are connected to a function can not be redefined, like the attribute names for hydrological constructions and hydrological features can be redefined.

In contrast with hydrological constructions and their properties, all constructions can have any or all of the following miscellaneous effects on the hydrological model.

Sewered constructions

Sewered constructions are constructions under which a sewer exists, and through which water can flow into the sewer. When a sewered connection overlaps with a sewer area, that overlap forms an actual sewer, with the storage capacity of the SEWER_STORAGE attribute of the sewer area. Any surface water entering the cell of a sewered construction is directly moved to the sewer (unless the sewer is filled to capacity).

Attribute	Unit	Function value	Description
SEWERED	boolean	Connected to sewer	Whether this construction is connected to the sewer.

Water storage constructions

Constructions capable of water storage can store some surface water without allowing it to flow back into the rest of the model. Water stored in constructions can not flow out or evaporate away.

Attribute	Unit	Function value	Description
WATER_STORAGE	m³/m²	Water storage (m³/m²)	How much water this construction can store.

Porous constructions

Some constructions are porous or open, and can allow water to infiltrate into the underground unsaturated zone.

The speed at which water can infiltrate is dependent on both the infiltration properties of the constructions as well as on the underlying surface terrain. Of the infiltration values of the construction and the surface terrain, the lowest value is used. If either has an infiltration value of 0, water cannot infiltrate into the underground unsaturated zone.

Attribute	Unit	Function value	Description
GROUND_INFILTRATION_MD	m/day	Ground infiltration per day (m)	The speed at which water can flow vertically from the surface to the underground unsaturated zone.

Crops and foliage

Constructions representing crops and foliage can draw water from the underground, allowing it to evaporate. This behaves in the same way as terrain which is configured as plants.

Attribute	Unit	Function value	Description
ROOT_DEPTH_M	m	Depth of plant roots (m)	The depth of the roots of this construction, relative to the terrain height at the location of this construction. Water can be drawn from the underground and evaporated if the roots can reach it.
WATER_EVAPORATION_FACTOR	factor	Water evaporation	How fast this construction can evaporate water from the underground. The weather's evaporation speed is multiplied by this factor to determine the rate of evaporation.

Note that when a construction is present in any given location, the values for evaporation will overrule any values set by terrain in the same location. To model underground evaporation without a construction, set these attributes on the applicable terrain type instead.

Critical structures

Some constructions may be considered critical, meaning the consequences of water stress are greater for these structures than for others. Examples include hospitals and (elementary) schools. Critical constructions will receive additional highlighting by the IMPACTED_BUILDINGS result type when the building is impacted by the amount of water defined by IMPACT_FLOOD_THRESHOLD_M.

By using different values for differing (kinds of) constructions, it is possible to have impacted structures highlight with different values as well. This makes it possible to differentiate in greater detail between the kinds of impacted structures.

Attribute	Unit	Function value	Description
CRITICAL_INFRASTRUCTURE	nominal integer	Critical infrastructure	Whether this construction is deemed a critical construction. 0 means the construction is never deemed impacted.

Chemical emitters/decomposers

Chemical emitters are constructions which produce specific chemicals. The net amount of chemicals a single construction creates is spread out across it's surface. After the chemicals are created, any water flowing through the same location will carry a part of the chemicals with it.

Chemicals have generic definitions, in terms of name and magnitude, to allow for the modeling of arbitrary substances.

Structures which are defined to create a negative amount of chemicals function as a scrubber or decomposer, removing the specified quantity of chemicals from the hydrological model.

In situations where water is absent, chemicals cannot move between cells.

Attribute	Unit	Description	Default
SUBSTANCE_A	x/m²	The amount of substance A created per second per m² in this location.	0
SUBSTANCE_B	x/m²	The amount of substance B created per second per m² in this location.	0
SUBSTANCE_C	x/m²	The amount of substance C created per second per m² in this location.	0
SUBSTANCE_D	x/m²	The amount of substance d created per second per m² in this location.	0

Chemical emitters's attributes do not take the form of function values, and must be added manually or as part of loading in geodata.

Manning value (construction)

Constructions have an inherent "roughness", which influences how fast water can flow across the surface. This is known as the Manning coefficient or Manning value.

Attribute	Unit	Terrain type	Description
WATER_MANNING	s/(m1/3)	Surface	The Gauckler–Manning coefficient of the construction.

Note that if no construction is present in any location, the WATER_MANNING value of the surface terrain present is used instead.

Construction height

Though not an explicit attribute or function value in and of itself, the height of constructions is taken into account when computing the flow of water above ground. Constructions are computed to have at most a height of DESIGN_FLOOD_ELEVATION_M. Lower constructions retain their own construction height. Taller constructions have their height capped at the attribute's value.

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.

Water

Water terrains are processed by the water model in a specific manner before the simulation is started. For each water terrain in the 3D world, the bottom of the water body is treated as a land surface in the same fashion as dry land. Water is then placed on it on the surface layer, up to the level defined by the overlapping water level area's WATER_LEVEL attribute. Terrains not marked as water terrain are not initiated with water.

Terrains marked as water are subject to an additional check for the WATER_STRESS result type. If the amount of water on a water terrain has not increased by more than ALLOWED_WATER_INCREASE_M relative to the water level area's water level, that terrain will not count as stressed for that result type. The amount of water on that location must be at least ALLOWED_WATER_INCREASE_M more than the water level area's water level.

Attribute	Unit	Terrain type	Description
WATER	boolean	Surface	Whether the specified terrain is a water terrain.

Plants

Terrains can be configured with plant-related attributes, similar to crops and foliage constructions, allowing it to draw water from the underground and evaporate it.

Attribute	Unit	Terrain type	Description
ROOT_DEPTH_M	m	Surface	The depth of the roots of this surface terrain, relative to the surface. Water can be drawn from the underground and evaporated if the roots can reach it.
WATER_EVAPORATION_FACTOR	factor	Surface	How fast this terrain can evaporate water from the underground. The weather's evaporation speed is multiplied by this factor to determine the rate of evaporation.

Note that when a construction is present in any given location, the values for evaporation of the construction will overrule any values set by terrain in the same location. This is also true if the construction has its evaporation values set to 0; they will overrule the terrain's values and thus not allow evaporation of underground water to occur.

Also note that the groundwater level reduction is inversely proportional to the WATER_STORAGE_PERCENTAGE, as the contribution of a given volume of water to the groundwater level increases when the capacity for water storage in the underground layer decreases.

Infiltration and storage

Based on the properties of the terrain, water may infiltrate into the underground water system.

The speed at which water can infiltrate from the surface to the underground unsaturated zone is dependent on both the infiltration properties of the surface terrain, as well as any construction in that location, if present. Of the infiltration values of the construction and the surface terrain, the lowest value is used. If either has an infiltration value of 0, water cannot infiltrate into the underground unsaturated zone.

Underground flow, or horizontal infiltration, are dependent on the infiltration properties of the underground, unless an aquifer exists the same location.

Attribute	Unit	Terrain type	Description
GROUND_INFILTRATION_MD	m/day	Surface	The speed at which water can flow vertically from the surface to the underground unsaturated zone.
GROUND_INFILTRATION_MD	m/day	Underground	The speed at which water can flow vertically from the underground unsaturated zone to the underground saturated zone, and horizontally through across the saturated zone.
WATER_STORAGE_PERCENTAGE	fraction	Underground	The percentage of the underground volume which can be filled with water. A lower percentage means the underground will be able to store less water, and the saturated zone will rise higher with the same amount of water in the underground layer.

Manning value (terrain)

Terrains have an inherent "roughness", which influences how fast water can flow across the surface. This is known as the Manning coefficient or Manning value.

Attribute	Unit	Terrain type	Description
WATER_MANNING	s/(m1/3)	Surface	The Gauckler–Manning coefficient of the terrain.

Note that if a construction is present in the same location, that construction's WATER_MANNING value is used instead.

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

Template:Editor ribbon The water model performs complex calculations, and multiple types of results can be provided. In principle, each overlay can be configured to display a single result type.

Result types can differ in the kind of data they display, the layer (surface or underground) of which they display that information, and how that data is recorded. Different result types can monitor data in the following ways:

• Start: The data is determined at the start of the simulation, and does not change afterwards.
• Last: The data is the latest value determined at the timestep the data is recorded. The values can increase and decrease between different timesteps. This mode is primarily used for monitoring progression.
• Maximum: The data is the highest value determined up until the timestep the data is recorded. The values can only increase or stay the same, but will never decrease. This mode is primarily used to gain insight into impact; the most severe situation any point had to endure.
• Total: The result of a running tally, counting the relevant data up until the timestep the data is recorded. The value can only increase or stay the same, but will never decrease. This mode is primarily used to gain insight into quantities rather than duration.

The following results types are available:

Result type	Unit	Display mode	Description
BASE_TYPES	Nominal value	Start	Categorization of the individual cells based on how they are processed by the water model, displaying which cells are considered to be specific features. 0: Cell on the edge of the project area 1: Water area 2: Land 3: Sewer 4: Water object 5: Breach Area 6: Active Breach
DEBUG_UV
DEBUG_WALLS
EVAPORATED	m (mm)¹	Total	The amount of water that has evaporated. The value is the sum of the quantities evaporated from the surface and the underground.
GPU_OVERVIEW	nominal integer	Maximum	Shows which GPU cluster calculated which part of the overlay.
GROUND_LAST_STORAGE	m (mm)¹	Last	The (effective) amount of water in the underground unsaturated zone.
GROUND_LAST_VALUE	m (mm)¹	Last	The distance between the surface and the groundwater level.
GROUND_MAX_STORAGE	m (mm)¹	Maximum	The (effective) amount of water in the underground unsaturated zone.
GROUND_MAX_VALUE	m (mm)¹	Maximum	The distance between the surface and the groundwater level.
GROUND WATERTABLE	m + datum	Last	The groundwater level, relative to datum.
IMPACTED_BUILDINGS	nominal integer	Maximum	Constructions impacted by excess water. Constructions are considered impacted when the construction itself or an adjacent cell contains more water on the surface than configured in IMPACT_FLOOD_THRESHOLD_M. 0: Construction is not impacted 1...N: The (critical) construction is impacted, and has a critical function values set to this value.
SEWER_LAST_VALUE	m (mm)¹	Last	The amount of water stored in the sewer.
SEWER_MAX_VALUE	m (mm)¹	Maximum	The amount of water stored in the sewer.
SUBSTANCE_A	x/m²	Last	The amount of substance A present. The value is the sum of the quantities on the surface, and in the underground.
SUBSTANCE_B	x/m²	Last	The amount of substance B present. The value is the sum of the quantities on the surface, and in the underground.
SUBSTANCE_C	x/m²	Last	The amount of substance C present. The value is the sum of the quantities on the surface, and in the underground.
SUBSTANCE_D	x/m²	Last	The amount of substance D present. The value is the sum of the quantities on the surface, and in the underground.
SURFACE_DIRECTION	angle (0-90°)	Last	The direction in which water is flowing across the surface.
SURFACE_DURATION	s (min)¹	Total	The amount of time the water depth on the surface exceeds SHOW_DURATION_FLOOD_LEVEL_M.
SURFACE_ELEVATION	m + datum	Start	The rasterized version of the terrain height for use in the water overlay's calculations.
SURFACE_FLOW	m³/m²	Last	The amount of water which has flowed either into or out of any given location.
SURFACE_LAST SPEED	m/s	Last	The speed of water flow in any given location.
SURFACE_LAST_VALUE	m (mm)¹	Last	The amount of water on the surface.
SURFACE_MAX SPEED	m/s	Maximum	The speed of water flow in any given location.
SURFACE_MAX_VALUE	m (mm)¹	Maximum	The amount of water on the surface.
WATER_STRESS	m (mm)¹	Maximum	The amount of water on the surface, similar to SURFACE_MAX_VALUE. However, for water terrains, the water level must rise by at least ALLOWED_WATER_INCREASE_M. Otherwise, the reported value in those locations is 0.

¹ the units between () are as displayed in the 3D client. If exported to GeoTiff the SI-convention is used: meters (m) and seconds (s).

Each result type would consist of a unique output of data after a calculation, and is accompanied by its own legend. When the result type of the overlay is changed, the legend is updated automatically, but the data may not be recalculated automatically. This may result in the visual output of the overlay changing, because the unchanged data is displayed with a new legend. When changing the result type, it is recommended to force a recalculation of the overlay before interpreting the output.

Result child overlays

Each overlay can only display a single result type. When using a water overlay, it is conceivable that multiple result types are relevant to a project's use case. It's possible to duplicate the overlay, and set the copy of the overlay to a different result type, but this is not recommended. Downsides of this approach are that the simulation has to run in full multiple times, causing a severe increase in calculation time, and that when changes to the overlay's configuration have to be made those changes need to be made to all water overlays.

It is possible to add result child overlays overlays to a water overlay, which can display different results coming forth from the same calculation. The advantages of using result child overlays are that for any given water overlay, the calculation of the overlay only occurs once, rather than multiple times equal to the amount of desired result types. Additionally, the configuration for the calculation is only defined in a single overlay, which makes it easier to make sure all results come forth from the exact same simulation.

Result child overlays do not recalculate if either they or their parent is set to inactive.

If a calculation overlay is removed, all result child overlays which are children of that overlay are removed as well. Separate overlays set as child overlays (such as input overlay) of the overlay will not be removed.

It is only possible to add result child overlays via the configuration wizard, in the output overlays step.

Attributes

The water model calculations rely on a number of calculation-wide parameters. These parameters are available as attributes of the water overlay and can be modified as such.

Attribute	Unit	Description
ALLOWED_WATER_INCREASE_M	m	The amount by which the water level on a water terrain must increase before it is considered stressed by water. This is used to compute the WATER_STRESS result type.
DESIGN_FLOOD_ELEVATION_M	m	Constructions in the 3D world are assumed to have at most this height compared to the surface of the terrain. Greater values can create a more accurate model but will impact performance.
GROUND_BOTTOM_DISTANCE_M	m	Assumed distance under the terrain surface where the soil becomes impenetrable for water. The groundwater level cannot go below this depth, relative to the surface. The maximum amount of water that can be stored underground is equal to this attribute multiplied by the local terrain's WATER_STORAGE_PERCENTAGE.
GROUND_WATER	boolean	Whether underground water flow is simulated during the calculation. If this is deactivated, surface infiltration, underground infiltration, and underground evaporation do not occur. Water flowing in- and out of the sewer are still simulated when sewers are present.
IMPACT_FLOOD_THRESHOLD_M	m	The amount of water a construction must experience before it is considered impacted by water. Water must reach this height either on one of the cells the construction is on, or on one of the cells adjacent to it. This is used to compute the IMPACTED BUILDINGS result type.
MAX_SPEED_MS	m/s	Maximum speed at which water is allowed to flow. This effects the preservation of impulse in water, and as a result the length of computational timesteps. Impulse is more accurately preserved as the maximum speed increases, but will reduce the time per step of the calculation, increasing the total time for the calculation to complete.
MIN_SLOPE	ratio	The minimum slope required to account for the effect of gravity on the speed of the water. If the slope of the terrain is less than the minimum slope, the effect of gravity on the speed of the water is assumed to be 0. The ratio is the height over distance.
QUAD_CELL	boolean	This attribute name is reserved for future functionality. Currently, this marks an experimental feature which is currently under development and may result in unexpected behavior when activated.
SEWER_OVERFLOW_THRESHOLD	fraction	How much of a sewer's storage must be filled with water before the sewer's overflows are allowed to overflow water.
SHOW_DURATION_FLOOD_LEVEL_M	m	The amount of water which must be present in a specific location before the duration of surface water can be recorded. This is used to compute the SURFACE_DURATION result type.
SURFACE_WATER_EVAPORATION_FACTOR	factor	The factor by which the weather's evaporation factor is multiplied to compute the amount of evaporation which takes place on the surface.
TIMEFRAMES	integer	The number of intermediate results recorded during the calculation. Each timeframe becomes a snapshot of data which can be viewed and analysed. The total simulation time is divided by this value, and at each interval of that period of time a snapshot of the results so far is made. Note that the first timeframe does not contain the starting conditions of the simulation, but the state of the simulation after the first period of time has passed.

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 conjuction form the water model in its entirety.

Surface model

The water model's primary function is the simulation of the flow of water on the surface of the terrain. The surface model includes the flow of water across the surface of the terrain, including over water terrains, including the flow through hydrological constructions and water that is created or removed by hydrological constructions.

The surface is defined by the terrain height in the project. The terrain height is further influenced by the height of constructions present in the project (bounded by DESIGN_FLOOD_ELEVATION_M) and by the BREACH_HEIGHT of breaches.

The surface water level is initialized based on hydrological features present in the project. For all water terrains, water is placed on the surface of the world. The amount of water placed is such that the resulting water level in that location is equal to the WATER_LEVEL attribute of the water level area in that location. If there is no water level area in that location, the water level is assumed to be so low that no water is created. Besides the water level areas, Inundation is added to the model. Water is placed in all locations where inundation is defined (regardless of the terrain type in that location, in contrast to the water level areas), such that the resulting height of the water inundating the land is equal to the inundation area's INUNDATION_LEVEL attribute.

After the surface is initialized with water, all water on the surface will flow in accordance with the same rules. It does not matter whether the water was created when the model was initialized, and whether that water was due to a water terrain or due to inundation, or whether the water came in from another source.

On the surface, water can flow from one cell to an adjacent cell based on the relative heights of the water, the slope of the terrain, and the manning value of the terrain or construction in that location.

In addition to water flowing between geographically adjacent cells, water can also flow through hydrological constructions. When a line-based hydrological construction exists in the project area, the 2 cells indicated by the endpoints of the line are considered adjacent as well. Flow between those cells is not dictated by the same parameters as the regular surface flow. Instead, water can flow between the 2 indicated cells based on the construction's underlying formula.

Water can also be added to or removed from the water model by point-based hydrological constructions. Based on the construction's underlying formula water can be added or removed to the cell indicated by the construction. Only that single cell will receive or lose the calculated amount of water.

Water can also be removed from the surface by other properties of constructions, based on the construction's polygons (either moving it to another part of the hydrological model, or removing it completely from the hydorlogical model). When water is removed from the surface via a polygon-based construction, the removal of water is calculated per individual cell.

Underground model

The water model includes an underground model which dictates the movement of water in the soil. The underground model includes the flow of water from the surface into the underground via infiltration, the flow of water from one underground location to another, and the exfiltration of water from the soil back onto the surface layer.

The underground model can be explicitly activated or deactivated by setting the GROUND_WATER attribute of the water overlay to the appropriate value. If the underground model is deactivated, no water can move from or to the underground in any form, including underground evaporation.

The underground is bounded vertically by the surface of the terrain at the top, and an assumed impenetrable layer at the bottom. The distance between the surface and the impenetrable layer, and thus the effective height of the underground, is equal to GROUND_BOTTOM_DISTANCE_M. In other words, the impenetrable underground layer is assumed to be a set distance below the surface. The distance is uniform across the entire project area, and follows the profile of the surface.

The underground is composed of 2 layers: the unsaturated zone and the saturated zone. The saturated zone is the region of the underground where the soil is saturated with water. This water is assumed to work as a continuous volume of water able to flow horizontally. The unsaturated zone is the region of the underground above the saturated zone. The edge between the unsaturated and saturated zone can be considered the groundwater level.

The groundwater level, and thus the height of the saturated zone, is determined both by the amount of water in the saturated zone, and the underground terrain's WATER_STORAGE_PERCENTAGE. The lower the water storage percentage of the soil, the greater the volume of soil that is saturated by the same amount of water, and thus the higher the the groundwater level will become.

The underground water level is initialized with the values of the ground water GeoTIFF connected to the water model. If no ground water data is connected, the ground water level relative to datum is equal to the surface water level relative to datum, as defined by the WATER_LEVEL attribute of the water level area in that location.

When water infiltrates from the surface, it infiltrates at a speed dictated by the surface terrain's GROUND_INFILTRATION_MD attribute, the underground terrain's GROUND_INFILTRATION_MD attribute, or (if present) by the construction's GROUND_INFILTRATION_MD, whichever value is lowest. The least porous material present will always serve as a bottleneck for the water to flow through, even if the other layers allow for a high rate of infiltration.

Surface water infiltrates into the underground unsaturated layer. Water in the unsaturated layer is assumed to be spread equally across the entire unsaturated volume. Water then flows from the unsaturated zone into the saturated zone at the speed dictated by the underground terrain's GROUND_INFILTRATION_MD. For a given timestep, the distance the water travels is determined. The amount of water that flows from the unsaturated zone to the saturated zone is equal to the amount of water in a section of the unsaturated zone the height of which is equal to that distance. After water has been added to the saturated zone, the groundwater level (and thus the height of the saturated zone) is redetermined. The water in the unsaturated zone is redistributed uniformly across the (remaining) unsaturated zone.

Water stored in the underground saturated zone can flow horizontally from one underground cell to another, if the groundwater level relative to datum is higher than the neighboring cell's ground water level, relative to datum. The amount of water which can flow from one cell to another is dictated by the underground terrain's GROUND_INFILTRATION_MD.

Water stored in the underground saturated zone can also exfiltrate out of the underground and back onto the surface, if the groundwater level relative to datum exceeds the neighboring cell's surface water level relative to datum. The amount of water which can flow from the underground of one cell onto the surface of an adjacent cell is dictated by the underground terrain's GROUND_INFILTRATION_MD.

Rain model

Rain is implemented in the water model.

Rain can be implicitly activated and deactivated by defining an appropriate period of rainfall in the weather. If a period with no rainfall is defined, that period is simulated but no rain is simulated.

Currently, during a period in the simulation where rainfall is defined, water is uniformly added to the surface of all cells in the project area. During any single defined period of rain, the amount of rain is consistent over time. At the end of the defined period of rain, exactly the defined amount of rain will have fallen on each cell.

Evaporation model

Water can evaporate from the hydrological model over time. Multiple forms of evaporation are implemented.

All forms of evaporation can be implicitly activated and deactivated by setting the weather's evaporation rate. If the evaporation factor is set to 0, no evaporation will take place in any form.

The weather's evaporation rate is defined as a period during which a certain rate of evaporation will take place. Multiple periods of evaporation can be defined, and at any specific moment during the simulation an exact evaporation rate is defined by the weather.

For all forms of evaporation, the weather's evaporation rate is used as a base for determining the exact rate of evaporation for that form of evaporation.

Surface evaporation model

Water can evaporate from the surface, based on the weather's evaporation factor and the overlay's SURFACE_WATER_EVAPORATION_FACTOR. These values compute to a net rate of evaporation which is applied to the surface of all cells. Only water on the surface of cells is affected by this evaporation.

Cells without water on the surface are not affected by evaporation.

Underground evaporation model

Water can evaporate from the underground if the cell has either a construction which allows for underground evaporation, or a surface terrain type which allows for underground evaporation and is unobstructed by a construction. In other words: if a construction is present the construction's properties are used, otherwise the terrain's properties are used.

Underground evaporation can be implicitly activated or deactivated by setting the relevant properties of all terrain types and constructions to appropriate evaporation values. If the relevant properties are set to 0, no underground evaporation will take place. Underground evaporation is also explicitly deactivated when the underground model is deactivated.

Water can evaporate from the underground via crops and foliage. It can draw water from the underground unsaturated and saturated zones, if their roots reach deep enough and the terrain or construction have a configured evaporation factor. Water is drawn directly from the underground and evaporated, removing it from the hydrological model entirely.

The rate of evaporation is determined by the weather's evaporation rate, and either the construction's WATER_EVAPORATION_FACTOR or the surface terrain's WATER_EVAPORATION_FACTOR.

Evaporation can only take place if the roots of the terrain or construction can reach underground water. The depth the roots can reach is defined by either the construction's ROOT_DEPTH_M or the surface terrain's ROOT_DEPTH_M.

Water can be evaporated both from the saturated and the unsaturated zones of the underground. The amount of water that can be taken from the saturated and the unsaturated zones is limited by the amount of water in either zone in reach of the roots.

Sewer model

Sewers are available in the water model, allowing for the retention of excess water which would otherwise stay and flow on the surface.

Sewers can be implicitly activated and deactivated by adding or removing sewer areas. If no sewer areas exist, no sewers are available in the water model and no water can flow to and from there.

Sewer areas define the areas in which sewers exist. The capacity of those sewers is based on the sewer area's SEWER_STORAGE attribute. The actual locations where the sewer exists is the intersection between the sewer areas and the sewered constructions in the project area. The total surface area of the actual sewer is equal to that intersection.

If there is water on the surface, in a cell with a sewered construction, and there is a sewer present in the same location, the water flows directly into the sewer. Water can flow in until the sewer is filled to capacity. Water can only flow into a sewer a via sewered construction. It is not possible for water to flow from a sewer back to the surface via a sewered construction, unless that construction is is explicitly a sewer overflow.

Water can flow from a sewer overflow back onto the surface via a sewer overflow. A sewer overflow removes water from the sewer and places it on the surface of the cell where the overflow is located. The speed at which this water flows is determined by the SEWER_OVERFLOW_SPEED.

To overflow from the sewer to the surface, two criteria need to be met. Firstly, the amount of water in the sewer relative to the sewer's total capacity must exceed the SEWER_OVERFLOW_THRESHOLD. Secondly, the water level in the sewer must exceed the terrain height at the location of the sewer overflow.

Water can be removed from a sewer based on the sewer area's SEWER_PUMP_SPEED. Water removed from the sewer in this way is removed entirely from the hydrological model.

Storage model

Water on the surface can be stored in water storage constructions.

Water storage in constructions can be implicitly activated or deactivated by ensuring that all constructions in the project area have appropriate water storage properties. If there are no constructions in the project area with water storage capacity, no water storage will take place.

When water flows onto a cell with a construction capable of storing water, that water will be stored in the construction until the construction's water storage capacity has been reached. Water cannot leave that storage, either through flow back into the hydrological model or by being removed from it altogether. When the storage is filled, no additional water cannot flow into that storage for the remainder of the simulation.

Chemical flow model

Chemicals can be modeled in the hydrological model, as quantities picked up and carried along with the water.

The chemical model can be implicitly activated and deactivated by having construction in the project area have the appropriate attributes configured. If no constructions have attributes configured to interact with the quantities of chemicals, then no chemicals are computed.

Chemicals are tracked as an exact amount on a given location. The substances are generically defined and do not have a set unit or magnitude.

Chemicals are added to the hydrological model and removed from the hydrological model by chemical emitters and decomposers. The chemicals created are then placed on the surface of the cells where they are created. Chemicals can also be removed by chemical constructions, if their attributes are configured appropriately. When chemicals enter the cell which contains a chemical decomposer, the chemicals are removed from the hydrological model.

When water moves from a cell which also contains chemicals, the chemicals are carried along with the water. The chemicals are uniformly distributed between the water which remains in the cell, which flows to other cells, and which infiltrates. Water which flows into the sewer explicitly cannot carry chemicals along with it.

Model border

The outer edge of cells of the water model are excluded from calculations. No water can flow from or to there.

Formulas

The precise calculations which govern the water overlay's simulation are many and varied, and based as much as possible on available expert knowledge.

Timestep formula

An adaptive timestep is implemented according to Kurganov and Petrova (2007). At every timestep, the courant-number is kept smaller than 0.25 for every active computation cell.

Especially at low depths, choosing the appropriate timestep is critical to avoid numerical instability. Therefore the following principles are used to determine the right time step:

• the timestep is choosen so that all computation cells follow one of the following criteria.
• if a cells waterdepth is below the flooding threshold, 5 * 10^-3 (m) there is no flow assumed between that cell and it neigboring cell.
• if the cells waterdepth is above above the flooding threshold, the maximum timestep is assumed to be 100 * the waterdepth at the cell.
• if the waterdepth increases, the timestep is assumed to be not larger than the formula above.

If the numerical flux decreases, larger timesteps are allowed than set by Kurganov and Petrova, depending on the configured calculation.

Calculation preference formula

The calculation preference influences the calculation of individual timesteps.

Δt = Δx /u_max

Where:

• Δt = computational timestep

• Δx = grid cell size
• u_max = max velocity, assumed 2.5 (SPEED), 5 (AVERAGE) and 10 (ACCURACY) m/s respectively

Surface water level formula

Surface water level is calculated per cell.

WL_surface = W_surface + H_surface

Where:

• WL_surface = The water level, relative to datum.

• W_surface = The amount of water (the water column) on the surface.
• H_surface = The terrain height in the cell, relative to datum.

Surface flow formula

Surface flow is calculated using the 2D Saint Venant equations.

2D Saint Venant

The base equations describe the conservation of mass and momentum in both the x and y direction.

The following processes are described in these equations:

• friction
• bed slope
• water pressure
• convection (changes in bathemetry over space)
• inertia (increase or decrease of velocity over time)

Numerical scheme for the 2D Saint Venant equations

Source: Horváth et al. (2014)

Source: Horváth et al. (2014)

The explicit second-order semi-discrete central-upwind scheme for the 2D Saint Venant Equations is implemented. A reconstruction of cell bottom, water level and velocity at the interfaces between computational cells as proposed by Lax and Wendroff (Rezzolla, 2011). The Tygron Platform's water model relies on the scheme described in Kurganov and Petrova (2007). The reconstruction method is taken from Bolderman et all (2014) and ensures numerical stability at the wetting and drying front of a flood wave.

A clear explanation on the numerical approach can be found at Horváth et al. (2014), but in general it follows these steps:

1. The elevation value of the cell (denoted as B in included figures) is equal to the elevation value at the center of the cell. At the same time, it is equal to the average value of the elevation values at the cell interface midpoints.
2. The slopes of the conserved variables (denoted as U in included figures), continuity and momentum in x and y direction, are reconstructed.
3. Values of conserved variables at the cell interface midpoints are compared with the left-sided and right sided values at cell centers.
4. At partially dry cells, the slope is modified to both avoid negative depths and numerical instability.
5. (Numerical) fluxes are computed at each cell interface to determine the values of the conserved variable at the cell centers for the next time-step.

Groundwater level formula

Groundwater level is calculated per cell.

WH_underground = W_sat / WSP

WL_underground = WH_underground + H_surface - GBDM

Where:

• WL_underground = The groundwater level, relative to datum.
• WH_underground = The height (column) of the saturated zone.

• W_sat = The amount of water in the saturated zone. The height of the water column if the equivalent amount of water was placed on the surface.
• H_surface = The terrain height in the cell, relative to datum.
• GBDM = The GROUND_BOTTOM_DISTANCE_M (effectively available height in the underground model).
• WSP = The WATER_STORAGE_PERCENTAGE of the underground terrain type.

Surface infiltration formula

Surface infiltration is calculated per cell.

Infiltration capacities:

C_water = W_surface

C_top = max( I_con, I_surf )

I_surf = 0 if a construction is present

I_con = 0 if no construction is present

Actual infiltration:

Δw = min( C_water , Δt * C_top)

Where:

• Δw = The surface infiltration which takes place.
• Δt = Computational timestep.

• C_water = The amount of infiltration that can take place based on the amount of water on the surface.
• C_top = The amount of evaporation that can take place based on the infiltration values present.

• W_surface = The amount of water (the water column) on the surface.
• I_con = The GROUND_INFILTRATION_MD of a construction on a specific cell (if present).
• I_surf = The GROUND_INFILTRATION_MD of the surface terrain type. This value should be interpreted as the vertical conductivity (Kv) of the sub-soil.

Underground infiltration formula

Underground infiltration (from the unsaturated zone to the saturated zone) is calculated per cell.

First the height of the unsaturated zone is calculated.

H_unsat = H_surface - WL_underground

Then the ratio of water amount to unsaturated height is calculated.

S = W_unsat/H_unsat

Then calculate the distance of the unsaturated zone which can infiltrate.

C_inf = min( H_unsat , Δt * I_und )

Finally, calculate the amount of actual amount of water infiltrating.

Δw = C_inf * S

Where:

• Δw = The underground infiltration which takes place.
• Δt = Computational timestep.

• H_unsat = The height of the unsaturated zone.
• S = Ratio of water to height in the unsaturated zone.
• C_inf = The height in the unsaturated zone which can be subject to infiltration to the saturated zone.

• W_unset = The amount of water in the unsaturated zone. The height of the water column if the equivalent amount of water was placed on the surface.
• WL_underground = The groundwater level, relative to datum.
• H_surface = The terrain height in the cell, relative to datum.
• I_und = The GROUND_INFILTRATION_MD of the underground terrain type.

Underground flow formula

Underground flow is calculated differently from surface flow, to account for the slowdown and porousness of the medium.

In general, Darcy's law is used. When an aquifer is present a variant is applied.

Darcy's law

Underground flow between cells is calculated using Darcy's law.

C_d = Δt * I_und * width * A * ( (WL_source - WL_target) / distance )

Since both width and distance are directly related to the cell size, and the result should be in water height rather than volume, the formula can be rewritten as follows:

C_d = Δt * I_und * A * (W_source - W_target) / cell

Because the underground may have a different porousness, the maximum amount of water that can flow to another cell has to take into account the relative water storage capacities of the underground.

C_wsp = (WL_source - WL_target) * (WSP_source / (WSP_source + WSP_target) )

The amount of water which flows from the source to the target cell is calculated as follows:

Δw = max( 0 , min( C_d , C_wsp ) )

Where:

• Δw = The underground flow which takes place.
• Δt = Computational timestep.
• cell = Cell size.

• C_d = The capacity for water flow possible based on the relative water heights.
• C_wsp = The capacity for water flow possible based on the relative water storage percentages.

• WL_source = The amount of water in the saturated zone of the source cell. The height of the water column if the equivalent amount of water was placed on the surface.
• WL_target = The amount of water in the saturated zone of the target cell. The height of the water column if the equivalent amount of water was placed on the surface.
• A = Contact area of the underground cells
• I_und = The GROUND_INFILTRATION_MD of the underground terrain type of the origin cell.
• WSP_source = The WATER_STORAGE_PERCENTAGE of the underground terrain type of the origin cell.
• WSP_target = The WATER_STORAGE_PERCENTAGE of the underground terrain type of the target cell.

Aquifer formula

When an aquifer is present, its hydraulic diffusivity is used to calculate the water flow.

First, the hydraulic diffusivity dictates the fraction of the water height difference which will flow.

F = 2 * sqrt( KD / WSP_source ) * sqrt( Δt ) * ( 1 / cell )

Based on this fraction, the actual amount of water flow is calculated.

Δw = ( (WL_source/WSP_source) - (WL_target/WSP_source) ) * F

Where:

• Δw = The underground flow which takes place.
• Δt = Computational timestep.
• cell = Cell size.

• F = Fraction of water which flows between cells

• KD = The AQUIFER_KD attribute of aquifer.
• WSP_source = The WATER_STORAGE_PERCENTAGE attribute of the underground terrain type of the origin cell.
• WSP_target = The WATER_STORAGE_PERCENTAGE attribute of the underground terrain type of the target cell.
• WL_source = The amount of water in the saturated zone of the source cell. The height of the water column if the equivalent amount of water was placed on the surface.
• WL_target = The amount of water in the saturated zone of the target cell. The height of the water column if the equivalent amount of water was placed on the surface.

Culvert formula

Flow through culverts is based on an open channel flow calculation.

The actual height of the culvert is at least the height of the terrain on either end of the culvert:

CH_real = max( CH_attr , T_left , T_right )

The height of the water column at either end of the culvert, relative to the culvert, is calculated:

WH_left = max(0, WL_left-CH_real)

WH_right = max(0, WL_right-CH_real)

The loss coefficient for the culvert is calculated:

U = sqrt( 1.0 / ( 1.0 + 2.0 * G * CN * CN * length / (Rh ^ (4 / 3 ) ) )

The potential flow through the culvert is then calculated:

C = U * A * sqrt( 2 * G * abs(WH_left - WH_right) )

Finally the actual amount of water flow is calculated:

Δw = Δt * C / cell

Where:

• Δw = The water flow which takes place.
• Δt = Computational timestep.
• cell = Cell size.

• C = The potential rate of water flow through the culvert.
• U = Loss coefficient for culverts.
• WH_left = The height of the water column relative to the bottom of the culvert on the left side of the culvert.
• WH_right = The height of the water column relative to the bottom of the culvert on the right side of the culvert.
• CH_real = The CULVERT_THRESHOLD of the culvert, recalculated so the culvert is not below ground on either side.

• A = Flow area, based on the height of the water in the (circular) culvert.
• G = Acceleration factor of gravity
• CW = The CULVERT_DIAMETER attribute of the culvert.
• CH_attr = The CULVERT_THRESHOLD attribute of the culvert.
• CN = The CULVERT_N attribute of the culvert.
• WL_left = The water level on the left side of the culvert, relative to datum.
• WL_right = The water level on the right side of the culvert, relative to datum.
• L = The length of the culvert, calculated as the distance between the culvert's endpoints.
• Rh = The hydrological radius in the culvert.

Weir formula

Flow across weirs is calculated differently for free flow and submerged flow.

The height of the water at each end of the weir, relative to the weir, is calculated:

WH_source = max(0, max( WL_left, WL_right ) - WH_weir)

WH_dest = max(0, min( WL_left, WL_right ) - WH_weir)

For free flow, capacity is calculated directly:

C_free = DWF * WC * WW * ( WH_source - WH_dest )^3/2

For submerged flow, a culvert-like calculation is used:

C_submerged = U * A * sqrt( 2 * G * (WH_source - WH_dest) )

Based on the relative water heights, the weir is judged to have either a submerged flow or a free flow, based on the following ratio:

WH_relative = WH_dest : WH_source

C = min( C_submerged , C_free) if WH_relative > 0,5

C = C_free otherwise

Finally the actual amount of water flow is calculated:

Δw = Δt * C / cell

Where:

• Δw = The water flow which takes place.
• Δt = Computational timestep.
• cell = Cell size.

• C = The potential rate of water flow across the weir.
• WH_relative = The ratio of water heights on either side of the culvert.
• C_free = The potential rate of water flow across the weir, based on a free flow calculation.
• C_submerged = The potential rate of water flow across the weir, based on a submerged calculation.
• WH_source = The height of the water column relative to the top of the weir, on the side with the highest water level.
• WH_dest = The height of the water column relative to the top of the weir, on the side with the lowest water level.

• U = Loss coefficient for submerged weirs (0,9).
• A = Flow area, based on the highest water column height relative to the top of the weir, and the weir width, defined by the WEIR_WIDTH attribute of the weir
• G = Acceleration factor of gravity
• DWF = Dutch weir factor, set to 1.7
• WC = The WEIR_COEFFICIENT attribute of the weir.
• WH_weir = The WEIR_HEIGHT attribute of the weir.
• WL_left = The water level on the left side of the weir, relative to datum.
• WL_right = The water level on the right side of the weir, relative to datum.

Breach growth formula

Breaches can grow when water flows from the virtual external water source into the hydrological model.

First, the difference in height of the water on either side of the breach is calculated.

H = abs( max(0, EL - BH) - max(0, WL - BH) )

Using the height difference, the breach width increase is calculated.

ΔB = 1.3 * ((G^0.5 * H^1.5) / Uc) * log10 (1 + (0.04 * G / Uc) * Δt / 3600)

The current breach width is then equal to the last calculated breach width, plus the calculated additional breach width.

B_new = B_old + ΔB

Where:

• B = The total calculated breach width, initially equal to BW.
• Δt = Computational timestep.

• ΔB = The calculated width increase of the breach.
• H = The difference between the height of the water columns on either side of the breach.

• MF = Material factor, set to 1.3 (average for sand and clay levees)
• G = Acceleration factor of gravity
• BH = The BREACH_HEIGHT attribute of the breach.
• BW = The BREACH_WIDTH attribute of the breach.
• BS = The BREACH_SPEED attribute of the breach.
• EL = Current external water level.

Breach flow formula

Main section: Weir formula

Flow through breaches is calculated based on the weir formula, including the consideration between free flow and submerged flow situations. However, the following also applies.

For the virtual side of the breach, the water level used is defined by the external water level of the breach. The terrain height used for the virtual side of the breach is equal to the external surface level, limiting how far the external water level can be lowered.

Each timestep, the external water level is changed based on the amount of water flowing in or out.

EL_new = EL_old - ( (Δw * cell) / EA )

Where:

• Δw = The water flow which takes place (out of the virtual external water source)
• cell = Cell size

• EL = EXTERNAL_WATER_LEVEL attribute of the breach.
• EA = EXTERNAL_AREA attribute of the breach.

Pump formula

The flow created by a pump is calculated based on the lowest end point of the pump.

Δw = min( WH_lower , Δt * PS )

Where:

• Δw = The amount water water pumped from the lower to the higher endpoint.
• Δt = Computational timestep.

• WH_lower = The height of the water column at the lower end of the pump, relative to the terrain.
• PS = The PUMP_SPEED of the pump.

Overflow formula

Overflow from the sewer is calculated for the entirety of the sewer, and the single attached sewer overflow.

The amount that can overflow relies on both the sewer overflow itself as well as the sewer overflow threshold:

C_threshold = max( 0 , WH_sewer - SS * SOT )

C_height = max( 0, T_sewer + SO + WH_sewer - T_overflow )

C = min ( C_threshold, C_height )

Actual overflow is then calculated:

Δw = min( 0 , C * Σ_sewer , Δt * SOS )

where:

• Δw = The amount of sewer overflow which takes place.
• Δt = Computational timestep.

• C = The amount of water that can overflow out of the sewer
• C_threshold = The amount of water that could overflow, based on the sewer overflow threshold.
• C_height = The amount of water that could overflow, based on the properties of the sewer overflow.

• Σ_sewer = The surface area of the sewer.
• WH_sewer = The height of the water column in the sewer.
• T_sewer = The average height of the terrain where the sewer is present, relative to datum.
• T_overflow = The height of the terrain at the centerpoint of the sewer overflow, relative to datum.
• SO = The SEWER_OVERFLOW attribute of the sewer overflow.
• SOS = The SEWER_OVERFLOW_SPEED attribute of the sewer overflow.
• SS = The SEWER_STORAGE attribute of the sewer area.
• SOT = The SEWER_OVERFLOW_THRESHOLD.

Inlet formula

The amount flowing in or out of inlets is calculated for the cell the inlet resides on.

When calculating inlets, first the capacities are calculated.

If a T_lower is defined:

C_inthres = max( 0 , T_lower - WL_surface )

If a I_Q is defined:

C_speed = Δt * I_Q

If a C_total is defined:

C_incap = C_used - C_total

After calculating the capacities, the actual water inflow is calculated.

Δw = max( 0 , min( C_inthres , C_speed , C_incap ) ) / cell

If any of the terms are undefined, they are not included.

When calculating outlets, first the capacities are calculated.

If a T_lower is defined:

C_outthres = min( 0 , T_upper - WL_surface )

If a I_Q is defined:

C_speed = Δt * I_Q

If a C_total is defined:

C_outcap = -C_total - C_used

After calculating the capacities, the actual water ouflow is calculated.

Δw = min( 0 , max( C_outthres , C_speed , C_outcap) ) / cell

If any of the terms are undefined, they are not included.

After the water flow (either inflow or outflow) is computed, the capacity is updated.

C_used (new) = C_used (old) + (Δw * cell)

Where:

• Δw = The amount of water flow which takes place.
• Δt = Computational timestep.
• cell = Cell size.

• C_speed = The amount of water inflow (or outflow when negative) possible based on the inlet's INLET_Q attribute.
• C_incap = The amount of water inflow possible based on the total capacity of the inlet.
• C_outcap = The amount of water outflow possible based on the total capacity of the outlet.
• C_inthres = The amount of water inflow desired based on the inlet's LOWER_THRESHOLD attribute.
• C_outthres = The amount of water outflow desired based on the outlet's UPPER_THRESHOLD attribute.

• WL_surface The water level on the surface, relative to datum.
• C_total = The INLET_CAPACITY attribute of the inlet.
• I_Q = The INLET_Q attribute of the inlet.
• T_lower = The LOWER_THRESHOLD attribute of the inlet.
• T_upper = The UPPER_THRESHOLD attribute of the inlet.

Surface evaporation formula

Surface evaporation is calculated per cell.

Δw = min( WL_surface , Δt * E_weather * E_overlay )

where:

• Δw = The amount of evaporation which takes place.
• Δt = Computational timestep.

• W_surface = The amount of water (the water column) on the surface.
• E_weather = The evaporation rate of the weather.
• E_overlay = The SURFACE_WATER_EVAPORATION_FACTOR.

Underground evaporation formula

Underground evaporation is calculated per cell.

Evaporation capacities:

For all underground evaporation, the height of the unsaturated zone is used.

H_unsat = H_surface - WL_underground

First the capacity for saturated evaporation is calculated, based on how much of the saturated area is in contact with the roots.

C_sat = max( 0 , min( RD , GBDM ) - H_unsat ) * WSP

Next the height of the unsaturated zone, and based on that the capacity for unsaturated evaporation is calculated.

C_unsat = max( 0 , min( RD , H_unsat ) ) * ( W_unsat / H_unsat )

Finally, the actual evaporation is calculated:

Δw_unsat = min( C_unsat , Δt * E_weather * E_top )

Δw_sat = min( C_sat , (Δt * E_weather * E_top) - Δw_unsat )

Δw = Δw_unsat + Δw_sat

Where:

• Δw = The total amount of evaporation which takes place.
• Δt = Computational timestep.

• Δw_unsat = The amount of evaporation which takes place from the unsaturated zone.
• Δw_sat = The amount of evaporation which takes place from the saturated zone.
• C_sat = The amount of evaporation that can take place from the saturated zone.
• C_unsat = The amount of evaporation that can take place from the unsaturated zone.
• H_unsat = The height (column) of the unsaturated zone.

• W_unsat = The amount of water in the saturated zone. The height of the water column if the equivalent amount of water was placed on the surface.
• WL_underground = The groundwater level, relative to datum.
• H_surface = The terrain height in the cell, relative to datum.
• RD = The ROOT_DEPTH_M of the construction if present, the ROOT_DEPTH_M of the surface terrain otherwise.
• GBDM = The GROUND_BOTTOM_DISTANCE_M (effectively available height in the underground model).
• E_weather = The evaporation rate of the weather.
• E_top = The WATER_EVAPORATION_FACTOR of the construction if present, the WATER_EVAPORATION_FACTOR of the surface terrain otherwise.

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

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.