14.7 Mass Balance Output
Mass balance information for TUFLOW Classic or HPC, and TUFLOW 1D (ESTRY), is generated by setting Mass Balance Output to ON (the default). Due to the different mathematics employed for the two 2D solvers, the information produced varies between Classic and HPC.
14.7.1 Mass Balance Definitions
TUFLOW reports the “Volume at Start” and “Volume at End” for a simulation in the .tlf (Section 14.4.1). These are instantaneous spatial integrals of surface water (not ground water) across both 1D and 2D domains. “Volume at End” should be the “Volume at Start” plus the time integral of “Volume In”, less the time integral of “Volume Out”. However, “Volume In” and “Volume Out” are not as simple as they sound. These are defined as:
Volume In:
- 2D integral of “Sink-Source” over cells where it is positive.
- 2D edge inflows (QT, HT, HQ) on cells where the flow is entering the domain.
- 2D integral of groundwater recharge to surface.
- 1D node inflows.
Volume Out:
- (negative of) 2D integral of “Sink-Source” over cells where it is negative.
- 2D edge outflows (QT, HT, HQ) on cells where the flow is leaving the domain.
- 1D node outflows.
Sink-Source is defined on a cell by cell basis as the “vertical” movement of water:
- (add) RF rainfall (negative RF is included only if cell is wet).
- (add) SA source-area (negative SA is included only if cell is wet).
- (subtract) material losses.
- (subtract) infiltration losses.
Note that Sink-Source can be negative, in particular when the rain has stopped but water is still infiltrating into the ground. Importantly, infiltration losses under rainfall cause the “Volume In” to be less than the simple area integral of rainfall, rather than showing as “Volume Out”.
14.7.2 TUFLOW 1D Mass Balance
For simulations with a TUFLOW 1D (ESTRY) component, if Mass Balance Output is ON the following mass balance output is available for 1D:
- As discussed in Section 14.1.1 the cumulative mass error percentage appears as three numbers after the letters “CE” in the Console Window. This data is also output to the .tlf file (Section 14.4.1). The first percentage is the overall model (all 1D and 2D domains) and the second is for all of the TUFLOW 1D domains (the third discussed in Section 14.7.3) (see the description of the “Cum ME (%)” column in Table 14.4 and Table 14.5). Monitoring these numbers is important so as to establish the “health” of the model, as discussed in Section 16.1. Ideally all these percentages should be within ±1%. Much higher numbers may occur at the start of a simulation, especially if there are 2D domain(s) rapidly wetting. This should not be an issue provided the model quickly settles down and the CE percentages fall within acceptable amounts.
- The _MB1D.csv file contains mass balance reporting for all the 1D (ESTRY) domains (see Table 14.5). It is written to the .ecf Output Folder.
- Time based 1D mass error is output as a GIS layer to a _TSMB_P.shp layer (see Table 14.7 for a description of the attributes). Using GIS thematic mapping of the ME_Avg_Abs attribute is a powerful way of identifying any problematic 1D nodes.
- Time based mass error reporting across 1D/2D HX links is output as a GIS _TSMB1d2d layer. Note, when viewing this layer that each 1D node point object is connected to a collection of 2D cell objects that make one overall GIS object (called a Collection). This layer is also useful for identifying which 2D cells are connected to a 1D node for the 2D HX links. See Table 14.8 for a description of the attributes. Using GIS thematic mapping of the ME_Avg_Abs attribute is a powerful way of identifying any problematic 2D HX links.
14.7.3 TUFLOW Classic Mass Balance
For TUFLOW Classic simulations, if Mass Balance Output is ON the following mass balance output is available:
- As discussed in Section 14.1.1 the cumulative mass error percentage appears as three numbers after the letters “CE” in the Console Window. This data is also output to the .tlf file (Section 14.4.1). The first percentage is the overall model (all 1D and 2D domains), the second is for all of the TUFLOW 1D domains and the third for all of the 2D domains (see the description of the “Cum ME (%)” column in Table 14.4, Table 14.5 and Table 14.6. Monitoring these numbers is important so as to establish the “health” of the model, as discussed in Section 16.1. Ideally all these percentages should be within ±1%. Much higher numbers may occur at the start of a simulation, especially if there are 2D domain(s) rapidly wetting. This should not be an issue provided the model quickly settles down and the CE percentages fall within acceptable amounts.
- Two _MB.csv files are output by TUFLOW reporting on the various inflows and outflows, volume, predicted volume error and the mass and cumulative mass errors as a percentage as follows:
- The _MB.csv file is for the overall model (all 1D and 2D domains) (see Table 14.4). It is written to the .tcf Output Folder .
- The _MB2D.csv file contains mass balance reporting for all 2D domains together and for each individual 2D domain if using Classic’s Multiple 2D Domain feature (see Table 14.6). The _MB2D.csv is written to the .tcf Output Folder. These files also report inflows and outflows across HX and SX connections for 1D/2D links between TUFLOW’s 1D scheme (ESTRY) and other external 1D schemes (e.g. FloodModeller or SWMM). The overall mass balance reported does not include flows in any external 1D scheme, but does include flows across links to an external 1D scheme.
- The _MB.csv file is for the overall model (all 1D and 2D domains) (see Table 14.4). It is written to the .tcf Output Folder .
- Map output of the 2D mass error can be output by specifying the MB1 and/or MB2 option for Map Output Data Types. Both MB1 and MB2 outputs are a measure of the convergence level of the solution. The measure is a cumulative value since the last output time, and is an effective way of identifying problem areas in a model that repeatedly have poor convergence and most likely mass error. The MB1 output is accumulated since the previous output time and the MB2 output is accumulated over the entire simulation.
It is possible to specify different time intervals for the display on the screen and the _MB.csv output files. The .tcf command Mass Balance Output Interval is used for setting the interval in the _MB.csv files.
A summary of key model performance indicators is also reported at the end of the simulation in the Console Window and .tlf file (see Section 16.1.3).
Healthy TUFLOW Classic models fall within ±1% cumulative mass error (see Section 16.1 for discussion on “unhealthy” models). If a model experiences higher mass errors this may be due to the following:
- Poor numerical convergence due to using too large a timestep and/or areas of the model are slightly unstable (major instabilities will generate warnings and eventually an error).
- Models with significant areas of complex hydraulics, or steep and very shallow flows when using the direct rainfall approach (Read GIS RF). These models should be tested using double precision versions of TUFLOW Classic (see Section 13.3.2). This scenario may also require the default wet/dry depth (Cell Wet/Dry Depth) to be reduced to minimise mass errors that can arise from cells frequently wetting and drying with larger wet/dry depths.
- Poorly configured 1D/2D or 2D boundaries that are causing oscillations to occur.
- High frequency of repeated wetting and drying.
- Models located at high elevations above sea level, especially if the inflows are relatively small or direct rainfall is applied. These models should be run using double precision versions of TUFLOW Classic (see Section 13.3.2). There are no fixed guidelines for when to switch to double precision, other than to carry out sensitivity tests using single and double precision versions (as a general rule for Classic, not HPC, all direct rainfall models and models with elevations greater than 100 to 1,000m usually require or will benefit from using double precision).
- 1D nodes that are frequently drying (undershooting), or are being limited if Head Rate Limit is being used (not recommended) can result in mass errors. The _TSMB and _TSMB1d2d GIS layers are useful for reviewing 1D mass error. These files report the mass error values as a flow rate in m3/s (or ft3/s if using
Units == US Customary ) so that they can be compared with the total flow through the model at that location (i.e. a mass error of 1m3/s at a node where 1,000m3/s is passing through is not an issue, while it would be if only 2m3/s was passing through the node).
- Note that the calculation of mass errors will not detect errors in the model flow boundary inputs. It is recommended that conventional mass balance checks be carried out (irrespective of the software used) as a matter of course as a cross-check that the correct amount of water is entering and leaving the model (see Section 16.3).
| Column | Description |
|---|---|
| Time (h) | The simulation time in hours. |
| H Vol In | The volume of water in m3 flowing into the model across water level (HQ, HS, HT) boundaries since the previous time. |
| H Vol Out | The volume of water in m3 flowing out of the model across water level (HQ, HS, HT) boundaries since the previous time. |
| Q Vol In | The volume of water in m3 flowing into the model from flow (QH, QS, QT, RF, SA, ST) boundaries since the previous time. |
| Q Vol Out | The volume of water in m3 flowing out of the model across flow (QH, QS, QT, RF, SA, ST) boundaries since the previous time. |
| Tot Vol In | The total volume of water entering the model since the previous time in m3. |
| Tot Vol Out | The total volume of water leaving the model since the previous time in m3. |
| Vol I-O | “Tot Vol In” minus “Tot Vol Out” (i.e. the net volume of water in m3 entering the model since the previous time). |
| dVol | The change in the model’s volume since the previous time in m3. |
| Vol Err | “dVol” minus “Vol I-O” (i.e. the volume error or amount of water in m3 unaccounted for since the previous time). A positive value indicates the solution may have gained mass, while a negative value indicates a possible mass loss. |
| Q ME (%) | (“Vol Err”/“Vol I+O”)*100 (i.e. the percentage mass error based on the volume of water flowing through the model since the previous time). This figure can be large at the start of a simulation if there are 2D cells rapidly wetting and the flow through the model (“Vol I+O”) is relatively small. This is a characteristic of 2D domains, particularly when using the direct rainfall approach. If “Vol I+O” is less than 1m3, “Q ME (%)” is set to zero to avoid divide by zero calculations. |
| Vol I+O | “Tot Vol In” + “Tot Vol Out” (i.e. the volume of water in m3 entering and leaving the model since the previous time). |
| Tot Vol | The total volume of water in the model in m3. |
| Cum Vol I+O | The cumulative volume of water entering and leaving the model in m3 (i.e. the cumulative total of “Vol I+O”). |
| Cum Vol Err | The cumulative volume error in m3 (i.e. the cumulative total of “Vol Err”). |
| Cum ME (%) | (“Cum Vol Err”/max(“Tot Vol” and “Cum Vol I+O”))*100 (i.e. the percentage mass error based on the maximum of the volume of water that has flowed through the model and total volume of water in the model). This figure can be large at the start of a simulation if there are 2D cells rapidly wetting and the flow through the model (“Cum Vol I+O”) is relatively small. This is a particular characteristic of steep models, particularly when using the direct rainfall approach. This figure can also be misleadingly low if the model has a very large volume of “stagnant” water such as a lake or part of the ocean. If max (“Tot Vol” and “Cum Vol I+O”) is less than 1m3, “Cum ME (%)” is set to zero to avoid divide by zero calculations. This figure is the first number displayed after “CE” on the Console Window. |
| Cum Q ME (%) | (“Cum Vol Err”/“Cum Vol I+O”)*100 (i.e. the percentage mass error based on the cumulative volume of water that has flowed through the model). This figure can be large at the start of a simulation if there are 2D cells rapidly wetting and the flow through the model (“Cum Vol I+O”) is relatively small. This is a particular characteristic of steep models, particularly when using the direct rainfall approach. If “Cum Vol I+O” is less than 1m3, “Cum Q ME (%)” is set to zero to avoid divide by zero calculations. |
| Column | Description |
|---|---|
| Time (h) | The simulation time in hours. |
| H V In | The volume of water in m3 flowing into all 1D domains at 1D water level (HQ, HS, HT) boundaries since the previous time. |
| H V Out | The volume of water in m3 flowing out of all 1D domains at 1D water level (HQ, HS, HT) boundaries since the previous time. |
| SX2D V In | The volume of water in m3 flowing into all 1D domains from 2D SX links since the previous time. |
| SX2D V Out | The volume of water in m3 flowing out of all 1D domains from 2D SX links since the previous time. |
| Q V In | The volume of water in m3 flowing into all 1D domains from 1D flow (QH, QS, QT) boundaries, except for 1D QT Regions, since the previous time. |
| Q V Out | The volume of water in m3 flowing out of all 1D domains from 1D flow (QH, QS, QT) boundaries, except for 1D QT Regions since the previous time. |
| QR V In | The volume of water in m3 flowing into all 1D domains from 1D QT Region flow boundaries, since the previous time. |
| QR V Out | The volume of water in m3 flowing out of all 1D domains from 1D QT Region flow boundaries, since the previous time. |
| Q2D V In | The volume of water in m3 flowing into hidden 1D nodes from 2D QT flow boundaries, since the previous time. |
| Q2D V Out | The volume of water in m3 flowing out of hidden 1D nodes from 2D QT flow boundaries, since the previous time. |
| HX2D V In | The volume of water in m3 flowing into all 1D domains across 2D HX links since the previous time. |
| HX2D V Out | The volume of water in m3 flowing out of all 1D domains across 2D HX links since the previous time. |
| Vol In-Out | Sum of all the volumes in less the sum of all the volumes out (i.e. the net volume of water in m3 entering all the 1D domains since the previous time). |
| dVol | The change in the 1D domains’ volume in m3 since the previous time. |
| Vol Err | “dVol” minus “Vol In-Out” (i.e. the volume error or amount of water in m3 unaccounted for since the previous time). A positive value indicates the 1D domains may have gained mass, while a negative value indicates a possible mass loss. |
| Q ME (%) | (“Vol Err”/(ΣV In + ΣV Out))*100 (i.e. the percentage mass error based on the volume of water flowing through the 1D domains since the previous time). If (ΣV In + ΣV Out) is less than 1m3, “Q ME (%)” is set to zero to avoid divide by zero calculations. |
| Total Vol | The total volume of water in m3 in the 1D domains. |
| Cum Vol In+Out | The cumulative volume of water in m3 entering and leaving the 1D domains (i.e. the cumulative total of (ΣV In + ΣV Out)). |
| Cum Vol Error | The cumulative volume error in m3 (i.e. the cumulative total of “Vol Err”). |
| Cum ME (%) | (“Cum Vol Error”/max(“Cum Vol In+Out” and “Total Vol”))*100 (i.e. the percentage mass error based on the maximum of the volume of water that has flowed through the 1D domains and the total volume of water in the 1D domains). This figure can be misleadingly low if the 1D domains have a very large volume of “stagnant” water such as from lakes or part of the ocean. If max (“Cum Vol In+Out” and “Total Vol”) is less than 1 m3, “Cum ME (%)” is set to zero to avoid divide by zero calculations. This figure is the second number displayed after “CE” on the Console Window. |
| Cum Q ME (%) | (“Cum Vol Error”/“Cum Vol In+Out”)*100 (i.e. the percentage mass error based on the volume of water that has flowed through the 1D domains). If “Cum Vol In+Out” is less than 1 m3, “Cum Q ME (%)” is set to zero to avoid divide by zero calculations. |
| Column | Description |
|---|---|
| Time (h) | The simulation time in hours. |
| H V In | The volume of water in m3 flowing into the 2D domain/s at 2D water level (HQ, HS, HT) boundaries since the previous time. |
| H V Out | The volume of water in m3 flowing out of the 2D domain/s at 2D water level (HQ, HS, HT) boundaries since the previous time. |
| Es HX V In | The volume of water in m3 flowing into the 2D domain/s across HX links to TUFLOW 1D (ESTRY) domains since the previous time. Note, this figure includes any 2D QT boundaries and 2D links as these become HX links connected to hidden 1D nodes. |
| Es HX V Out | The volume of water in m3 flowing out of the 2D domain/s across HX links to TUFLOW 1D (ESTRY) domains since the previous time. Note, this figure includes any 2D QT boundaries and 2D links as these become HX links connected to hidden 1D nodes. |
| x1D HX V In | The volume of water in m3 flowing into the 2D domain/s across HX links to an external 1D scheme since the previous time. |
| x1D HX V Out | The volume of water in m3 flowing out of the 2D domain/s across HX links to an external 1D scheme since the previous time. |
| SS V In | The volume of water in m3 flowing into the 2D domain/s from 2D flow sources (RF, SA, SH, ST) boundaries since the previous time. |
| SS V Out | The volume of water in m3 flowing out of the 2D domain/s from 2D flow sources (RF, SA, SH, ST) boundaries since the previous time. |
| Es SX V In | The volume of water in m3 flowing into the 2D domain/s through SX links to TUFLOW 1D (ESTRY) domains since the previous time. |
| Es SX V Out | The volume of water in m3 flowing out of the 2D domain/s through SX links to TUFLOW 1D (ESTRY) domains since the previous time. |
| x1D SX V In | The volume of water in m3 flowing into the 2D domain/s through SX links to an external 1D scheme since the previous time. |
| x1D SX V Out | The volume of water in m3 flowing out of the 2D domain/s through SX links to an external 1D scheme since the previous time. |
| V In-Out | Sum of all the volumes in less the sum of all the volumes out (i.e. the net volume of water in m3 entering the 2D domain/s since the previous time). |
| dVol | The change in the 2D domain/s’ volume in m3 since the previous time. |
| V Err | “dVol” minus “V In-Out” (i.e. the volume error or amount of water in m3 unaccounted for since the previous time). A positive value indicates the 2D domain/s may have gained mass, while a negative value indicates a possible mass loss. |
| Q ME (%) | (“V Err”/(ΣV In + ΣV Out))*100 (i.e. the percentage mass error based on the volume of water flowing through the 2D domain/s since the previous time). This figure can be large at the start of a simulation if the 2D domain/s are rapidly wetting and the flow through the 2D domain/s is relatively small. This is a particular characteristic of steep 2D domains, particularly when using the direct rainfall approach. If (ΣV In + ΣV Out) is less than 1m3, “Q ME (%)” is set to zero to avoid divide by zero calculations. |
| Total V | The total volume of water in m3 in the 2D domain/s. |
| Cum V In+Out | The cumulative volume of water in m3 entering and leaving the 2D domain/s (i.e. the cumulative total of (ΣV In + ΣV Out)). |
| Cum V Error | The cumulative volume error in m3 (i.e. the cumulative total of “V Err”). |
| Cum ME (%) | (“Cum V Error”/max(“Cum V In+Out” and “Total V”))*100 (i.e. the percentage mass error based on the maximum of the volume of water that has flowed through the 2D domain/s and the total volume of water in the 2D domain/s). This figure can be large at the start of a simulation if the 2D domain/s are rapidly wetting and the flow through the 2D domain/s is relatively small. This is a particular characteristic of steep 2D domains, particularly when using the direct rainfall approach with builds prior to Build 2008‑08‑AA. This figure can also be misleading low if the 2D domain/s have a very large volume of “stagnant” water such as from lakes or part of the ocean. If max (“Cum V In+Out” and “Total V”) is less than 1m3, “Cum ME (%)” is set to zero to avoid divide by zero calculations. This figure is the third number displayed after “CE” on the Console Window. |
| Cum Q ME (%) | (“Cum V Error”/“Cum V In+Out”)*100, ie. the percentage mass error based on the cumulative volume of water that has flowed through the 2D domain/s. This figure can be large at the start of a simulation if the 2D domain/s are rapidly wetting and the flow through the 2D domain/s is relatively small. This is a particular characteristic of steep 2D domains, particularly when using the direct rainfall approach. If “Cum V In+Out” is less than 1m3, “Cum Q ME (%)” is set to zero to avoid divide by zero calculations. |
| Column | Description |
|---|---|
| ID | ID of the 1D node. |
| ME_Avg_Abs | The average of the absolute mass errors throughout the simulation. This is an excellent attribute for identifying 1D nodes that are regularly “bouncing”. By using the average of the absolute values, rather than the ME_Avg attribute below, any nodes that are bouncing either side of zero mass error will be identified. The best approach to identify these nodes is to using GIS thematic mapping tools to show, for example, large circles around nodes with high ME_Avg_Abs values down to small or no circle around nodes with zero ME_Avg_Abs values. The units are in m3/s. |
| ME_Peak_m3s | The peak (positive or negative) mass error in m3/s. |
| ME_Avg | The average mass error in m3/s. |
| Not_used | This attribute is not yet used. |
| t____ | The mass error in m3/s at time t____ hours. |
| Column | Description |
|---|---|
| ID | ID of the 1D node. The object appears as a 1D point for the node collectively combined with the 2D cells connected to that 1D node via the 2D HX link. |
| ME_Avg_Abs | The average of the absolute mass errors throughout the simulation. This is an excellent attribute for identifying HX links that have poor mass error or are “bouncing”. By using the average of the absolute values, rather than the ME_Avg attribute below, any HX links that are bouncing either side of zero mass error will be identified. The best approach to identify these links is to use GIS thematic mapping tools to differentiate the object display based on the ME_Avg_Abs values. The units are in m3/s. |
| ME_Peak_m3s | The peak (positive or negative) mass error in m3/s. |
| ME_Avg | The average mass error in m3/s. |
| Not_used | This attribute is not yet used. |
| t____ | The mass error across the 2D HX link in m3/s at time t____ hours. |
14.7.4 TUFLOW HPC Mass Balance
TUFLOW HPC writes the _MB_HPC.csv instead of the _MB2D.csv. The file contains mass balance tracking of volumes of water in and out, mass error calculations and other information (see Table 14.9). The HPC scheme, being a finite volume scheme, is mathematically volume conservative. However, small mass errors may arise due to rounding errors in the summation of fluxes around the cell faces. These mass errors are real but very small - they are a direct function of the numerical precision used. Further, the summation process for computing the total volume in the domain is also subject to rounding errors. These errors are not real but may show as a very slight jitter in the summation result from timestep to timestep. Note that single precision computations use approximately 8 significant figures, and double precision computations use approximately 16 significant figures.
Unlike Classic, the HPC scheme does not provide a 2D map output of estimated mass error as this is essentially always zero due to the finite volume scheme formulation. However, a running estimate of domain integrated mass error is computed considering all inflows and outflows and the running surface water volume integral. These metrics are written to the _MB_HPC.csv file in the .tcf Output Folder.
| Column | Description |
|---|---|
| Time (h) | Simulation time in hours. |
| iStep | Number of computational steps. |
| nRS_NaNs | Number of repeated timesteps due to Not a Number (NaN) occurring. A NaN occurs when the solution becomes unstable causing a divide by zero or other undefined calculation forcing a lowering and repeat of the timestep. |
| nRS_HCNs | Number of repeated timesteps due to High Control Numbers (HCN). A HCN means that one of the three stability criteria was exceeded by more than 20% forcing a lowering and repeat of the timestep. |
| dtTarget | The target timestep (ie. the preferred timestep) calculated from the stability criteria. A lower timestep may have been used if approaching a times series or map output time, as HPC will reduce the timestep so that the solution timestepping coincides with the output time. |
| tLastMax | Time of the last recorded maximum water level. |
| H Vol In | Volume in since the previous time via 2D H boundaries (HQ, HT). |
| H Vol Out | Volume out since the previous time via 2D H boundaries (HQ, HT). |
| S/RF Vol In | Volume in since the previous time from 2D source boundaries (RF, SA, ST, subsurface water return, infiltration). |
| S/RF Vol Out | Volume out since the previous time from 2D source boundaries (RF, SA, ST, infiltration). |
| HX Vol In | Volume in since the previous time via 2D HX boundaries. |
| HX Vol Out | Volume out since the previous time via 2D HX boundaries. |
| SX Vol In | Volume in since the previous time via 2D SX boundaries. |
| SX Vol Out | Volume out since the previous time via 2D SX boundaries. |
| V In-Out | Volume In less Volume Out of 2D domain. |
| dVol | Change in total volume of water within 2D domain. |
| V Err | “dVol” less “V In-Out”. |
| Total V | Total volume of water in 2D domain. |
| Q ME% | Mass error expressed as a percentage of “V Err”/(Vin + Vout). |
