XPSWMM and XPStorm allows users build 2D or 1D/2D hydraulic models. This section presents an overview of the 2D modeling process. 


General Considerations for building a 2D Model

Data Requirements

The minimum data requirements for setting up a 2D/1D hydraulic model are:

  1. A DTM with sufficient resolution and accuracy to depict the topography of all flowpaths and storage areas in the 2D domain(s). The vertical accuracy depends on the modeling objectives and budget constraints. However, for large scale models ± 0.2m is preferred, whilst for fine-scale urban models < ± 0.1m is recommended. The vertical accuracy is dependent on the typical depths of inundation in key areas.

  2. Cross-sections for any 1D flowpaths.

  3. If bed resistance varies over the model, geo-corrected aerial photography or other GIS layer from which material (land-use) zones are digitized for setting Manning’s n values.

  4. Boundary conditions (e.g. ocean water levels, catchment inflows, rainfall, evaporation, etc).

  5. Calibration data locations as points in a GIS layer. Peak levels should be attached as attributes to the calibration points.

  6. Surveys of key hydraulic controls such as levees / embankments (3D breaklines), culverts, bridges, etc.

1D Network Definition

1D link-node networks are developed in XPSWMM with the graphic toolset. Alternatively, a 1D network may be imported or dynamically linked to an external database.

The adequacy of the 1D domains is primarily dependent on the network representation adopted. In general, the finer the resolution the more accurate the model, but the longer the computing time. For stability reasons, the timestep for computation is normally controlled by the minimum channel length. The end result may require a compromise between the level of detail and the computational effort.

Different timesteps can be specified for 1D and 2D domains largely removing this constraint.

The first step in setting up a model is to define the flow patterns and to use each identified flow path as the basis for a channel of the network. Following this step the flow paths are linked at junctions, or nodes, and each node is considered as a storage element, which accepts the flow from the adjoining channels. In this way, the model is built up as a series of interconnected channels and nodes with the channels representing the flow resistance characteristics.

For compatibility with the mathematical assumptions, the channels would ideally have more or less uniform cross-sections with constant bottom slope and a minimum of longitudinal curvature. In practice this requirement cannot always be met, particularly where a fine resolution of detail is not required in a portion of the study area. In this case, a flow path is represented by an “equivalent” channel. Experience has indicated that in most cases an adequate calibration can be achieved by deriving a single channel equivalent to a number of series or parallel channels using the steady state Manning's relation for deriving the equivalent channel characteristics.

All nodes and channels are labeled with an ID. No two nodes or two channels can have the same ID. A node and a channel cannot have the same ID.

2D Cell Size

The cell sizes of 2D domains need to be sufficiently small to reproduce the hydraulic behavior. In xpswmm2D, all cells are square and the same size with a defined orientation. The cells are defined and edited with the 2D Area Extent tool in the Layer Control Panel.

2D Topography

2D domains are created by building them through a series of layers using the Layer Control Panel. The layers may be constructed using XPSWMM graphic tools, imported or dynamically linked to a number of database formats. These layers contain or access from other files information on the size and orientation of the grid, bed/ground elevations, bed material type or flow resistance value, and other data.

A 2D domain is automatically discretised as a grid of square cells. Each cell is given characteristics relating to the topography such as ground/bathymetry elevation, bed resistance value and initial water level, etc.

Recommended Boundary Conditions Arrangements

Hydraulic models typically have water level boundaries at the downstream end and flow boundaries at the upstream ends.

For tidal models, the only boundaries may be ocean water level boundaries with pre-defined flows into or out of the system. For flood models, there are major flows into the upstream boundaries representing the catchment runoff. Occasionally, an upstream water level boundary is used in the absence of reliable river flow estimates. Where the downstream boundary is not at a well-defined water level (e.g. ocean), a stage-discharge relationship may be specified. In some situations, a hydraulic structure that is inlet controlled acts as the downstream control, in which case, the water level specified downstream of the structure has no influence on the results.

For 2D domains, water level boundaries exhibit the greatest stability (Syme 1991). Flow or velocity boundaries are difficult to specify as the flow direction and distribution across the boundary needs to be defined by the user. Wetting and drying of flow boundaries is also prone to instabilities.

Specifying boundaries oblique to the grid (i.e. not parallel to the grid axes or not at 45° to the axes) is also difficult in 2D fixed grid domains. However, xpswmm2D has an oblique boundary method that stabilizes water level boundaries. This facility is by default on, but can be adjusted using Oblique Boundary Method. For details of the method see Syme 1991.

The recommended approach for 2D flow boundaries is to dynamically link a 1D node to a 1D/2D interface boundary and apply the flow to the 1D node (Syme 1991). The inflow to the 1D node, generates a flow into the 2D domain across the 1D/2D interface boundary. This combination benefits from the stability, wetting and drying performance and the oblique boundary flexibility of water level boundaries. The velocity distribution and direction across the 1D/2D interface boundary is automatically determined by the flow regime that develops in the 2D domain.

2D boundary conditions line along the edge of 2D active areas jus as outfalls are connected to the end of a 1D network. When creating boundaries, use the snap tool so that the polyline coincides with the vertices of the active polygons.

Calibration and Sensitivity

Models are usually calibrated against known flood or tidal conditions with the bed resistance coefficient (eg. Manning’s n) adjusted until calculated water levels and flows are consistent with recorded field measurements. Where there is poor or insufficient topographic data the calibration procedure may also involve adjustments to the model topography to provide an adequate representation of the recorded flow behavior. This is more common in 1D domains (where there is a choice of cross-sections to define a flowpath). There is usually little opportunity to adjust topography (from that surveyed) in 2D domains.

Ideally, the model would be calibrated for conditions similar to those under investigation although this is not always possible, particularly when major floods are being considered. In these situations, a sensitivity analyses maybe carried out by increasing and decreasing calibration factors such as Manning’s n.

Limitations and Recommendations

XPSWMM and XPStorm are designed to model free-surface flow in coastal waters, estuaries, rivers, creeks, floodplains and urban drainage systems. Flow regimes through structures are handled by adaptation of the 1D St Venant Equations and the 2D Shallow Water Equations using standard structure equations. Supercritical flow areas can be represented.

Limitations and recommendations to note are:

  1. In areas of super-critical flow through the 2D and 1D domains, the results should be treated with caution, particularly if they are in key areas of interest. Hydraulic jumps and surcharging against obstructions may occur in reality – these highly 3D localized effects are not modeled.

  2. Where the 2D cell size is less than the water depth, the Smagorinsky viscosity formulation is preferred over the default constant viscosity formulation to model sub-cell turbulence (Barton 2001). It is always good practice to carry out sensitivity tests to ascertain the importance of the viscosity coefficient and formulation.

  3. Caution should be used when using 2D cell sizes less than 2m, particularly when the flow depth exceeds the cell width (Barton 2001).

  4. Modelling of hydraulic structures should always be cross-checked with desktop calculations or other software, especially if calibration data is unavailable. All 1D and 2D schemes are only an approximation to the complex flows that can occur through a structure, and regardless of the software used should be checked for their performance (Syme 1998, Syme 2001).

  5. There is no momentum transfer between 1D and 2D connections. Although in most situations this is not of concern, it does influence results where a large structure (relative to the 2D cell size) is modelled as a 1D element.

  6. There is a practical limit to the ultimate density of the 2D grid domain – in the current version 2 million grid cells is the upper range of the total cell count limit which is recommended. This is principally due to the very large 2D results files (*.dat files) which can be created when solving a model with this number of cells. In general, there can be issues with attempting to manipulate (open/close, read/write…ect) individual files upwards or greater than 2GB in size. If a large number of grid cells is required for your project and very large results files are being written (over 2GB files) then adjusting the output interval of the 2D results within the 2D job control is one way to reduce the output file sizes. Further, if a given 2D grid domain is needed to be very large (2 million grid cells or more) inorder to accommodate a required grid resolution as well as the grid coverage area, using multiple 2D domains may provide flexibility to use different 2D grid domains with different grid resolutions in different areas in the model. This can allow for the total number of grids in the model to be significantly reduced.

Check List

The table below presents a generalized list to help guide reviewers and modelers in carrying quality control checks on the modeling. This list is not exhaustive, and experienced modelers who know what to look for must at all times carry out the reviews.

Quality Control Check List

Item

Description

Checked

Modeling Log

A modeling log is highly recommended and should be a requirement on all projects. The log may be in Excel, Word or other suitable software. A review of the modeling log is to be made by an experienced modeler. It should contain sufficient information to record model versions during development and calibration, along with observations from simulations. A model version naming and numbering system needs to be designed prior to the modeling. The version numbering system should be reflected in input data filenames to allow traceability and the ability to reproduce an old simulation if needed.


File Naming, Structure and Management

A review of the data file management should check:

  • files are named using a logical and appropriate system that allows easy interpretation of file purpose and content;

  • a logical and appropriate system of folders is used that manages the files;

  • relative path names to be used for input files (eg. “..\model\geometry.tgc”) so that models are easily moved from one folder to another.

  • documentation of the above in, for example, the projects Quality Control Document and/or Modeling Log.


2D Cell Size

Check whether the 2D cell size is appropriate to reproduce the topography needed to satisfactorily meet the objectives of the study.


Topography

The topography review should focus on:

  • correct interrogation of DTM;

  • correct datum;

  • modifications to the base data (eg. breaklines) have been checked.

Regarding the latter, this is effectively carried out by producing a _zpt GIS check file using Write Check Files. The _zpt layer contains all modifications including any flow constriction adjustments. A DTM can be created from the Zpts using Vertical Mapper, or other 3D surface software, to aid in the review. Note: Reviewing the elevations in the .2dm file is not appropriate as only the ZH Zpt is represented in the .2dm file (the ZH elevation is not used in the hydrodynamic calculations).


Bed Resistance Values

Bed resistance values are to be reviewed by an experienced modeller. The review should focus on checking at least one of:

  • Roughnees Categories in the Global Database;

  • the grid “Mat” or “Manning_n” values in the _grd GIS check file; or

  • specifying weir output using the weir approach.

The reviewer should be looking for:

  •  relative consistency between different land-use (material) types; and

  •  values are within accepted calibration values.


Calibration / Validation

Check that the model calibration or validation is satisfactory in regard to the study objectives. Identify any limitations or areas of potential uncertainty that should be noted when interpreting the study outcomes.


Mass Conservation

Standard practice is to place PO flow lines at a minimum of several locations through the model. They are typically aligned roughly perpendicular to the flow direction. The locations should include lines just inside each of the boundaries. Other suitable locations are upstream and downstream of key structures, through structures and areas of particular interest.

The flows are graphed and conservation of mass checked (i.e. the amount of water entering the model equals the amount leaving allowing for any retention of water in the model). Check that any 1D flowpaths crossed by a PO line are also included in the mass check.

In dynamic simulations, an exact match between upstream and downstream will not occur due to retention of water, however, examination of the flow lines should reflect this phenomenon.

For steady-state simulations, demonstration of reaching steady flow conditions is demonstrated when the flow entering the model equals the flow leaving the model.


Free-Overfall & Weir Flow

Especially if Supercritical is set to OFF, the percentage of free-overfall and weir flow velocity points should be checked. The review should seek to check that excessive number of points are not free-overfalling, and if so:

that this is in accordance with the expected flow (e.g. weir flow over a levee) – check that the weir option is on if significant weir flow exists; and/or the affect on the overall flow patterns is minimal.

The review is best carried out by:

  • Monitoring the numbers after “CS” or “FO” on the screen or in the .tlf file

  • Specifying flow regime output to generate the _R.dat file. This file shows the flow regime.

The presence of significant areas of supercritical and/or weirs can be acceptable in large areas of sheet flow. However, care should be taken in interpreting the flow behavior in these areas, particularly if the flow is supercritical as complex hydraulic processes (e.g. hydraulic jumps, surcharging against buildings) can occur.

Typically, most supercritical and weir flow occurs:

  • around the edge of a model where it is wetting and drying and has little influence over the general flow behavior; or

  • down steep slopes or over significant drops (eg. over a levee).


Hydraulic Structures

Head losses through a structure need to be validated through:

  • Calibration to recorded information (if available).

  • Crosschecked using desktop calculations based on theory and/or standard publications (eg. Hydraulics of Bridge Waterways).

  • Crosschecked with results using other hydraulic software (e.g. HEC-RAS).

Simple checks can be made by calculating the number of dynamic head losses that occur and checking that this in accordance with that expected

It is important to note that contraction and expansion losses associated with structures are modeled very differently in 1D and 2D schemes. 1D schemes rely on applying form loss coefficients, as they cannot simulate the horizontal or vertical changes in velocity direction and speed. 2D schemes model these horizontal changes and, therefore, do not require the introduction of form losses to the same extent as that required for 1D schemes. However, 2D schemes do not model losses in the vertical or fine-scale horizontal effects (such as around a bridge pier) and, therefore, may require the introduction of additional form losses. See Syme 2001b for further details.


Eddy Viscosity

Check that the eddy viscosity formulation and coefficient is appropriate


Building 2D Models

1D/2D or 2D hydraulic models require domains, boundaries, and interfaces that define areas where 1D or 2D flow may occur. Their connections and boundary conditions can be further described using the tools within the interface. The model must be integrated with a Digital Terrain Model (DTM) to provide elevation vaules to the modeling objects. Topographic layers are used to further define 2D flow properties. Topographic layers such as Fill Areas, Dynamic Elevation Shapes, and Elevation Shapes have global adjustments available in version 2013 and later. Double-clicking on the object opens a dialog in which a change can be made. This change can then be applied to the selected object, all selected objects, or all objects of that type. 

Topographic Layers

2D Domains

2D Landuses

2D Landuses are polygons used to define areas of roughness and/or infiltration characteristics. Learn more about this this parameter in the 2D Landuses section

2D Flow Constrictions

Flow Constrictions allow the user to create points, lines and polygons that modify the 2D cell sides flow width, percentage blockage and additional energy losses for modelling 2D flow under and over bridges, pipes and other obstructions across a waterway. Read more about the use of 2D Flow Constrictions.

Additional considerations when building 2D models

Model Topography

The 2D model topography is defined by elevations at the cell centers, mid sides and corners. Each cell has the following elevations assigned to it:

  • “C” Zpt (ZC) – middle of cell

  • “U” Zpt (ZU) – middle right of cell

  • “V” Zpt (ZV) – middle top of cell

  • “H” Zpt (ZH) – top right hand corner of cell

The precision of the cell center elevation and 2D Map results can be set from 0 to 10 in version 2013 and later. The typical precision is 2 for US Customary projects and 3 for Metric models. 

For cell center elevation, you can change the precision in the Grid Extent Properties dialog.

For 2D Map results, you can change the precision for various 2D results. For example, when showing the Max Water Depth result for every cell, the Precision can be set to show 2 decimal places to represent one hundredth of a foot or every cm for a metric model. To change the precision:

  1. Right-click Max Water Depth in the Layers Control Panel and then select Properties.  
  2. In the dialog, select the Results Label tab.
  3. Modify the value in the Precision field.
Note: You can change the precision for Max Water Depth, Min Water Depth, Water Depth, Max Water Elevation, Min Water Elevation, Water Elevation, Max Hazard (VxD), and Hazard (VxD).

 

One of most important aspects of xp2D modeling is to understand the roles of the elevation points.

The ZC point:

  • defines the volume of active water (cell volume is based on a flat square cell that wets and dries at a height of ZC);

  • controls when a cell becomes wet and dry (note that cell sides can also wet and dry); and

  • is used to determine the bed slope when testing for the upstream controlled flow regime

The ZU and ZV points control how water is conveyed from one cell to another. If the cell has dried (based on the ZC point) the four ZU and ZV points on the cell sides are deactivated. ZU and ZV points also wet and dry independently of the cell wetting or drying.

ZH points play no role hydraulically. However, they elevations that are written to allow the 2dm mesh file, to be visible in other modeling programs such as SMS by Aquaveo or GIS programs.

 

2D Grid Orientation and Dimensions

Each 2D domain is a rectangle at any orientation. The orientation and dimensions are defined using the 2D Area Extent dialog. For the orientation it is recommended that the X-axis falls between 90° and –90° of East as it is preferable to view the 2D grid within this range and some post-processing software only operate within this range.

Several options are available for setting the grid location and orientation via an imported file. The options are:

  • Using a four-sided polygon in a GIS layer to define the 2D grid orientation and dimensions.

  • Using a line (two vertices only) in a GIS layer to define the orientation of the X-axis (see Read MI Location), and Grid Size (N,M) or Grid Size (X,Y) to set the 2D grid X and Y dimensions.

  • Using Origin, Orientation or Orientation Angle, and Grid Size (N,M) or Grid Size (X,Y). No GIS layers are required for this option.

It is not essential at any point to specify dimensions that are an exact multiple of Cell Size.

1D Boundary Conditions

Boundary conditions for the 1D link-node network are defined in the Hydraulics Node dialog. Boundary conditions may include:

  • Initial water levels
  • Constant or time variant inflow
  • Tailwater (several options)

2D Boundary Condition Layers

2D domain boundary conditions, including links and interfaces to both 1D and additional 2D domains, are defined using one or more 2D Boundary Condition GIS layers. Fixed field text inputs are also supported for backward compatibility. The different types of boundaries and links are described in the table.

The GIS layers may contain points, lines, polylines and regions, noting that for regions only the centroid is used. Each object has several attributes as described in table below.

2D Boundary Condition Types and Links to 1D Nodes

Type

Description

Comments

Water Level Boundaries

2D

Links two 2D domains

“Stitches” two 2D domains together by a series of water level control points. Momentum across the link is preserved provided the Zpt elevations along the selected cells in both 2D domains are the same or similar.

HS

Sinusoidal (Tidal) Water Level (m)

A sinusoidal wave based on any number of constituents. Four columns of data are required in the source file if using .csv files. The four columns in order are the mean water level (m), amplitude (m), phase difference (°) and period (h). Each row of data represents the harmonics of one wave. Any number of harmonics can be specified within the one HS boundary.  

HT

Water Level (Head) versus Time (m)

Assigns a water level to the cell(s) based on a water level versus time curve.

HX

Water Level (Head) from an external source (ie. a 1D model)

One or two 1D nodes provide a water level every half timestep. Automatically creates 1D QX boundaries at the node(s), which receive a flow from the 2D domain every half timestep. 2D HX boundaries are linked to 1D nodes using CN connections (see below).  

Tip: A common cause for instabilities is that the starting water level in the 1D node is different to those in the adjacent 2D cells. 

Treatment

Cell(s) can be wet or dry. It is not a requirement that at least one cell is wet. 

HT lines can be oblique to the X-Y axes, in which case, Oblique Boundary Method should be set to “ON” (this is the default). 

The water level can vary in height along a line of cells. 

Tip: A common cause of instabilities at or near head boundaries at the start of a simulation is the initial water level specified at the adjacent cells is different to the head value. If your model immediately goes unstable at the boundary, check your initial water levels. If it is a 2D HX boundary the water levels in the 1D node and the 2D cells should be similar. 

Combinations

Any number of water level boundaries can be assigned to the same cell(s). The water level used is the sum of the water levels assigned. For example, a storm tide may be specified as a combination of a tidal HS boundary, a HT boundary of the storm surge and another HT boundary of the wave setup. The HS boundary would be water elevations and the two HT boundaries water depths. 

The exception is that a 2D HX boundary, being a dynamically linked one, cannot be summed with another H boundary. In earlier versions of TUFLOW, if you accidentally specify a 2D HX boundary and a 2D HT or HS boundary at the same cell, the 2D HX boundary prevails and no warning is given. 

Flows (2D Flows With A Direction Component)

QC

Constant Flow (m3/s)

A constant flow boundary. At present, QC boundaries must be entered using the fixed field approach. The velocity is determined from the flow value and the model water levels. The direction of flow is required.

QT

Flow versus Time (m3/s)

Assigns a velocity and a flow direction to the sides of the cell(s) based on a flow versus time curve. The velocity is determined from the flow value and the water depths. The direction of flow is required.

VC

Constant Velocity (m/s)

Same as for a constant flow boundary (see QC above) except a velocity is specified.

VT

Velocity versus Time (m/s)

Same as for a QT boundary (see above) except a velocity is specified.

Treatment

Cell(s) can be wet or dry, however, it is recommended that cells remain wet, otherwise the quantity of flow is dependent on the number of wet cell(s) along the boundary.

QT lines should be specified along lines parallel or 45° to the X-Y axes.

These boundaries are rarely used, as dynamic links with 1D models are preferred with the flow boundary applied to the connecting 1D node.

Tip: It is strongly recommended to use a 1D node linked to a 2D HX boundary (see above) in preference to using a flow boundary, especially in flood models where there is major wetting and drying. This arrangement is far more practical, stable and flexible (the boundary can wet and dry, can lie oblique to the grid, and the velocity distribution and flow direction across the boundary is automatically determined).

Combinations

Any number of flow and velocity boundaries can be assigned to the same cell(s). The final velocity is the sum of the velocities assigned.

Sources (2D Flows With No Direction Component)

SA

Flow versus Time (m3/s) over an area,
or
Rainfall versus Time (mm)

Applies the flow directly to the cells within a polygon as a source. Negative values remove water directly from the cell(s). Most commonly used to model rainfall runoff directly onto 2D domains with each polygon representing the sub-catchment of a hydrology model. SA boundaries have their own command, Read MI SA, and own GIS layer.

The default option is to apply the boundary as a flow hydrograph as follows. Within each SA catchment (region), if all the 2D cells are dry, the flow is directed to the lowest cell based on the ZC elevations. If one or more cells are wet the total flow is distributed over the wet cells.

A rainfall hyetograph can be applied. The rainfall time-series data must be in mm versus hours, and is converted to a hydrograph to smooth the transition from one rainfall period to another. This approach applies a rainfall depth to every active cell (ie. Code 1 cells) within each region, and essentially replaces the need to use a hydrological model. Initial and continuing losses can be applied on a material-by-material basis. Note, this approach is being trialled and tested as of the time of writing and is considered an under-development feature that may be subject to change.

SH

Flow versus Head (m3/s)

Extracts the flow directly from the cells based on the water level of the cell. Used for modelling pumps or other water extraction. Flow values must not be negative. SH boundaries can be connected to another 2D cell or a 1D node, to model, for example, the discharge of a pump from one location in a model to another. The connection is made using a “SC” line (see below). In the boundary database, the Column 1 data would be head or water level values and the Column 2 data would be flow. The flow value is the rate per 2D cell. If the 2D cell becomes dry, no flow occurs.

ST

Flow versus Time (m3/s)

Applies the flow directly to the cells as a source. Negative values remove water directly from the cell(s). Can be used to model concentrated inflows, pumps, springs, evaporation, etc.

SX

Source of flow from a 1D model.

2D SX cell(s) are connected to a 1D node using a single CN connection (see below). The net flow into/out of the 1D node is applied as a source to the 2D cells. For example, a 1D pipe in the 2D domain “sucks” water out of the upstream cell(s) and “pours” water back out at the downstream cell(s) using 2D SX boundaries. 2D SX boundaries can also be used to model pumps.

Treatment

Sources are applied to all the specified cell(s) whether they are wet or dry, except for SA and SX, which apply only to wet cells, or the lowest dry cell if all the SA or SX cells are dry.

Combinations

Any number of source boundaries can be assigned to the same cell(s) whether they are SA, SH, ST or SX. The source rate applied is the sum of the individual sources.

Connections

CN
or
EC

Connection of 2D HX and 2D SX boundaries to 1D nodes

Used in GIS 2d_bc layers to connect 2D HX and 2D SX boundaries to 1D nodes. A line or polyline is digitised that snaps the 2D HX or SX object to the 1D node. The 1D node would be in a 1d_nwk layer. If the 2D HX or 2D SX snaps to the 1D node, no connection object is required. Alternatively a CN point object could be used.

As of Build 2003-06-AA, an ERROR occurs if a CN object is not snapped to a 2D HX or 2D SX object, or is redundant (ie. not needed). For backward compatibility, use Unused HX and SX Connections (.tcf file) or Unused HX and SX Connections (.tbc file) to change the ERROR to a WARNING. Note that for connections to 2D SX objects only one (1) CN object is required. Whereas 2D HX objects must have a minimum of two (2) connections – one at each end.

SC

Connection of 2D SH boundaries

Used for connecting 2D SH boundaries to another 2D cell or 1D node (eg. modelling the pumping of water from one location to another).

Wind Stresses

WT


Unsupported feature on PC version.

Treatment


Combinations


Variable Geometry

VG


Undocumented feature.

Treatment


Combinations


Other

CD


Objects in a GIS 2d_bc layer used to define the grid’s cell codes using Read MI Code BC as an alternative to Read MI Code. The code value is set using the f attribute.

The boundary lines are snapped to “CD” regions so that if the boundary location is adjusted, the boundary line and code region can move together.

IG


An object in a GIS 2d_bc layer can elected to be ignored by using the “IG” type.

Eddy Viscosity

Two options exist for specifying eddy viscosity for the 2D domains to approximate the effect of small-scale motions that cannot be modelled directly. Enter data using the Viscosity Formulation dialog in the 2D Job Control settings.

  1. The first method is to supply a constant value, E, which is used throughout the model. This is generally satisfactory when the cell size is much greater than the depth or when other terms are dominant (e.g. high bed resistance).
  2. The second method (Viscosity Formulation = Smagorinsky) is an approximation to the Smagorinsky formulation. This formulation is preferred when the cell size is similar or less than the depth.

Testing by Barton in 2001 indicates that 2D schemes using very fine elements (less than 2m) may have difficulty predicting correct flow behavior. Results from models with less than 2m cell size should be treated with caution, particularly if the depths are greater than the cell size and/or the friction forces are low (i.e. low Manning’s n).

How to Model Bridges and Box Culverts

Bridges, box culverts and other structures that constrict flow can be modeled in 2D rather than using 1D elements provided the flow width of the structure is of similar or larger size than the 2D cell size. Cells are modified in their height (invert and obvert) and width. For bridges, additional losses associated with flow reaching the underside of the deck is specified. For box culverts, the additional resistance for vertical walls is specified. Additional form losses (energy head losses) can be specified for all FCs.

Weir flow (across levees and other embankments) is modeled in 2D domains by default, but can be changed using options in the Free Overfall command. Weirs may also be modeled using 1D elements.

Modeling hydraulic structures in 2D domains must be carried out with a good understanding of the limitations of different approaches and the different flow regimes possible. The modeler must understand why and where the energy losses occur when assigning form losses to a 2D cell or contraction and expansion losses to a 1D element (Syme 2001b).

It is important to note that contraction and expansion losses associated with structures are modeled very differently in 1D and 2D schemes. 1D schemes rely on applying form loss coefficients, as they cannot simulate the horizontal or vertical changes in velocity direction and speed. 2D schemes model these horizontal changes and, therefore, do not require the introduction of form losses to the same extent as that required for 1D schemes. However, 2D schemes do not model losses in the vertical or fine-scale horizontal effects (such as around a bridge pier) and, therefore, may require the introduction of additional form losses. See Syme 2001 for further details.

It is strongly recommended that the losses through a structure be validated through:

    • Calibration to recorded information (if available).

    • Crosschecked using desktop calculations based on theory and/or standard publications (e.g. Hydraulics of Bridge Waterways, US FHA 1973).

    • Crosschecked with results using other hydraulic software.

To validate structure flows and energy losses:

    • Specify time-series output (PO) lines of flow (Q_) and flow area (QA) across the structure. Upstream and downstream water levels may also be specified or taken from the map (SMS) output.

    • Using the upstream and downstream water levels, determine whether flow is upstream or downstream controlled and estimate the flow using theoretical equations or other method.

    • Using publications such as Hydraulics of Bridge Waterways (US FHA 1973), determine the energy loss coefficient and compare this with the total energy loss calculated in the model. The total energy loss is the upstream head minus the downstream head (h1-h2) divided by the dynamic head based on the depth and width averaged velocity (V)  (i.e. Q_/QA) as given below. Clearly, any energy losses associated with bed resistance (e.g. Manning’s equation) need to be allowed for by taking this amount out of the (h1-h2) term.

    • Using other software (eg. HEC-RAS) create a check model using the flow and downstream water level as boundaries and compare the calculated upstream water levels.


Hydraulic Structure Modelling Approaches

Structure

1D Approach

2D Approach

Box Culvert
(For culverts with a steep slope, use a 1D element)

OK

OK

Circular Culvert

OK

N/A

Bridge

OK

OK

Weirs

OK

OK

1D Approach

Preferred approach where the total structure width is less than the cell size.

Entry and/or exit losses may need to be reduced where the structure width is significant compared with the cell size (Syme 2001b).

Momentum is not transferred into or out of the 1D element from the 2D domain. “Suppressed” flow patterns in the 2D domain occur at the structure outlet when using 1D elements, especially if the structure width is significant compared with the cell size. The water tends to spread out evenly, rather than jet out as occurs if using a 2D representation. This may be overcome by applying “wing walls” in the 2D domain at the structure outlet by assigning flood free elevations to the ZU and ZV Zpts either side of where the 1D element discharges into the 2D domain.

2D Approach

Preferred where the total structure width is greater than the cell size. The flow area must be adequately represented by the 2D Zpts and any adjustments to cell widths. The head drop across the structure during different flow regimes should be validated against other methods and/or literature.

Some additional form losses are normally required to achieve correct head drop (see Syme 2001b). Where the cell size is less than the depth, use the Smagorinsky Viscosity formulation. Care should be exercised using cell sizes less than 2m (Barton 2001).

Momentum is transferred through the structure, providing far more realistic flow patterns than using a 1D element.

2D Upstream Controlled Flow (Weirs and Supercritical Flow)

Where flow in the 2D domain becomes upstream controlled, xp automatically switches between either weir flow and/or upstream controlled friction flow.

If Supercritical is set to ON the following rules apply. Note: the bed slope at ZU and ZV points is determined as the slope from the upstream ZC point to the ZU or ZV point in the direction of positive flow.

  • Where the bed slope at a ZU or ZV point is in the same direction as the water surface slope, tests are carried out to determine whether the flow is upstream controlled or downstream controlled. The adopted flow regime is determined by comparing the upstream and downstream controlled regime flows (preference to the lower flow) and whether the Froude No exceeds 1 (unless changed by Froude Check). The equation used for upstream controlled flow is the Manning equation with the water surface slope set to the bed slope. The Froude It is recommended that the Froude No check be used (which is the default setting) as it provides more accurate switching. A further check that phases out the Froude Check as the water surface approaches the horizontal (otherwise in some situations, the flow would remain in the upstream controlled regime). This check can be disabled for backward compatibility using Froude Depth Adjustment.

  • Weir flow only occurs if the bed slope is adverse (different direction) to the water surface slope. Weir flow across 2D cell sides is modeled by first testing whether the flow is upstream or downstream controlled. If upstream controlled, the broad-crested weir flow equation is used to replace the calculations for downstream controlled (sub-critical) flow conditions. Weir flow maybe switched off using the Free Overfall options.

xp produces an increase in water level at transitions from supercritical flow to subcritical flow as occurs with a hydraulic jump. It does not, however, model the complex 3D flow patterns that occur at a hydraulic jump, as it uses a 2D horizontal plane solution. Results in areas of transition should be interpreted with caution. It is also important to be careful presenting results in areas of supercritical flow as complex flows (such as surcharging against a house) may occur that would yield higher localised water levels – it is good practice to also view the energy levels when providing advice on flood planning levels.

If Supercritical is set to OFF, and Free Overfall is set to ON (the default), weir flow may occur on both adverse and normal bed slopes.

The weir flow switch may be varied spatially over the grid by setting a weir factor of zero where there is to be no automatic weir flow. The weir factor also allows calibration or adjustment where the broad-crested weir equation is applied. The broad-crested weir equation is divided by the weir factor. Therefore, a factor of 1.0 represents no adjustment, while a factor greater than one will decrease the flow efficiency. Note: the weir factor is not the broad-crested weir coefficient. For further information, refer to Syme 2001b.

Computational Timestep

The selection of the timestep is critically important for the success of a model. The run time is directly proportional to the number of timesteps required to calculate model behavior for the required time period, while the computations may become unstable and meaningless if the timestep is greater than a limiting value. This is known as the Courant stability criterion.

The computation timestep in the 2D Job Control settings.

Note that time controls for 1D calculations are set in the Hydraulics Layer Control. Time controls for 2D calculations are set in the General section of the 2D Job Control settings.

See additional recommendations for computational time steps below.

2D Domains

For the 2D scheme, the Courant Number generally needs to be less than 10 and is typically around 5 for most real-world applications (Syme 1991). The computation timestep in the Job Control settings and should be set in accordance with this criterion as given in the equation below.

 

Where:

 = timestep, s

= length of model element, m

g = acceleration due to gravity, ms-1/2

H = depth of water, m

As a rule, the timestep is typically half the cell size. For steep models with high Froude numbers and supercritical flow, smaller timesteps may be required. It is strongly advised to not simply reduce the timestep if the model is unstable, but rather to establish why it is unstable and, in most instances, adjust the model topography, initial conditions or boundary conditions to remove the instability.

If the model is operating at high Courant numbers (>10), sensitivity testing with smaller timesteps to demonstrate no measurable change in results should be carried out.

The occurrence of high mass errors is also an indicator of using too high a timestep.

1D/2D Models

It is recommended that the time step of the 2D engine be equal to or an integer multiple of the time step of the 1D calculations (set in Hydraulics Layer Job Control). 

2d Results

This section describes the options for outputting and viewing 2D model results. 

Output files

Check Files

produces check files for quality control of a model’s input data. It is strongly recommended that models are quality controlled through reviews of the check files. Effective use of the check files can save days during a model’s development and application.


Filename or Prefix/Suffix

Description

2D Domains

_2d_bc_tables_check.csv

Tabular data as read from the boundary condition database via any 2d_bc layers and after any adjustments (eg. time shift). Provides full traceability to original data source.


_dom_check.mif

Contains a rectangle for each 2D domain.


_grd_check.mif

GIS .mif/.mid files of the final 2D grid. Represents the final grid including all modifications from the .tgc file, boundary specifications and flow constrictions.

Can also be written at different stages within a .tgc file. The file contains all modifications to the 2D grid at the point in the .tgc file that it is written.


_bc_check.mif

GIS .mif/.mid files of the final 2D boundary conditions (BC). Note, the layer does not include any 2D/1D connections (“CN” type).


_fc_check.mif

GIS .mif/.mid files of the final arrangement of flow constrictions (FC). The flow constrictions are written as individual square cells of the same shape as the grid cells, even if the FC was specified using points or lines/polylines.


_glo_check.mif

GIS .mif/.mid files of any gauge level output (GLO) location.


_lp_check.mif

GIS .mif/.mid files of any 2D longitudinal profile(s).


_po_check.mif

GIS .mif/.mid files of any 2D plot output location(s). The layer shows points and lines occurring from the cell centres, rather than their exact locations in the original file(s).


_zpt_check.mif

GIS .mif/.mid files of the final 2D Zpts. Represents the final Zpts including all modifications from the .tgc file, and any flow constrictions in the .tcf file.

Can also be written at different stages within a .tgc file. The file contains all modifications to the 2D Zpts at the point in the .tgc file that it is written. This allows checking of the elevations at different stages of building the topography.


1D Domains

_1d_bc_tables_check.csv

Tabular data as read from the boundary condition database via any 1d_bc layers and after any adjustments (eg. time shift). Provides full traceability to original data source.

_1d_ta_tables_check.csv

Tabular data as read from tables via the 1d_ta layers for cross-section, storage and other data. Provides full traceability to original data source and additional information such as hydraulic properties determined from a cross-section profile.

_bc_check.mif

GIS .mif/.mid files of the final 1D boundary conditions (BC). If no boundary conditions were specified, empty .mif/.mid files are written that can be used to set up a new layer.

_1d_hydprop_check.mif

Contains the hydraulic properties at the top of the hydraulic properties tables as attributes of the 1D channels. Other information such as the primary Manning’s n is also provided. Very useful for carrying out quality control checks on the 1D channels.

_1d_inverts_check.mif

Contains the inverts of the 1D nodes and at the ends of the 1D channels. Very useful for checking for smooth transitions from one channel to another and with the nodes.

_iwl_check.mif

GIS .mif/.mid files of the initial water levels at the 1D model nodes.

_nwk_check.mif

GIS .mif/.mid files of the final 1D model network. The channels are not written as exactly the same polylines as this information is not retained during the data input process.

Note that the Use_Chan_Storage_at_Nodes attribute is always shown as F (false), and information supplied in the Topo_ID, Branch, Chainage and some other fields maybe not be as per the original data as this information is not available at the time the check file is written.

As of Build 2005-05-AN the following additions/changes occurred:

Node symbology is displayed as a red circle for nodes connected to two or more channels, a larger magenta circle for nodes connected to one channel and a large yellow square for nodes not connected to a channel. This is very useful for checking for channel ends or nodes that are not snapped.

Any generated pit channels are shown as a small channel flowing from north to south into the pit node. The upstream pit channel node that is generated is also shown. The length of the pit channel is controlled by Pit Channel Offset.

The top and bottom elevations of the NA table at nodes is now shown using the Upstream_Invert and Downstream_Invert attributes.

2D/1D Models

_1d_to_2d_check.mif

Displays the 2D cells connected to 1D nodes via 2D HX and 2D SX 2d_bc objects. Cells connected to the same node are given the same colour to allow for easy visualization of whether the right connections have been made. Additional information is supplied through the attributes.

Simulation Log File

XPSWMM and XPStorm produces a log file (.tlf file) containing a record of the simulation. The file is very useful for establishing data input problems and identifying instabilities.

At key stages during the model development and application search the file for any “WARNING”, “CHECK” or “NOTE” messages. “WARNING” messages in particular should be checked regularly. An “ERROR” keyword indicates an unrecoverable error and causes the simulation to stop. As many errors as possible are trapped before stopping.

An “XY:” at the beginning of a line indicates the error, warning, check or other message has also been redirected to a .mif file. Opening the .mif file in the GIS often provides a far more rapid location of the message within the model domain(s) than via other ways.

Time-Series Output

Time series data output is available in the following forms:

  • _PO.csv and _LP< name>.csv files (also referred to as plot output (PO) or longitudinal profile (LP) data) created using 2d_po and 2d_lp layers). These files are typically used in spreadsheet software for graphing and analysing time-series results.

  • In the _TS.mif file (2d_po locations only). The _TS.mif file also contains all 1D time based output. This file is used for graphing time series output within a GIS.

 Use Model Output in the 2D Job Control Settings to control the output times.

Identifying the Start of an Instability

Instabilities usually start with a one or a few computational points “bouncing” as a result of poor convergence of the mathematical equations being solved. To help identify the start of an instability, negative depth warnings are issued if the depth in a 2D cell or a 1D node becomes falls below –0.1m. Negative depth warnings are usually a pre-cursor to an instability. It is not uncommon, particularly in areas of rapid wetting and drying for negative depths to occur before the computational point is made dry (inactive). Hence a buffer of – 0.1m is used before reporting a WARNING.

The WARNINGs are sent to the _messages.mif file. Bring these into your GIS and they point directly at the location of the negative depth. If the number of these warnings are substantial (eg. if a model remains stable but with minor instabilities), select some of the first negative depth warnings in the attribute data (Browser Window in MapInfo) and display just those. The warnings are in order of occurrence. By tracing through the negative depth warnings in the vicinity of the instability, the trigger point of the instability can often be located.

Mass Balance Output

Mass balance information is generated by checking the box in the Model Output in the 2D Job Control Settings. The cumulative mass error (CE) appears at the far right of the display lines on the DOS Window for each timestep displayed to the screen. A _MB.csv file is also created in the results folder. The file contains information at each display time on the inflows and outflows, volume, predicted volume error and the mass and cumulative mass errors as a percentage, for all 2D domains and each individual 2D domain.

The mass error values are based on dividing the estimated volume error by the average inflow/outflow through the domains. At the startup of a model, particularly when there is little or no flow, and or the model rapidly becomes wet, the cumulative mass error can appear high, however, this should drop away as the model “settles” down. The mass error is displayed as zero while there is less than 1m3/s of water moving through the model.

The majority of models should fall within +/-1% cumulative mass error. If a model experiences higher mass errors this maybe due to using too large a timestep and/or areas of the model are sensitive or slightly unstable. Models with significant areas of complex, steep flows and/or rapid wetting and drying usually experience higher mass errors than those with predominantly more benign, sub-critical flows.

Note that the estimation of mass errors is in itself a prediction and has errors associated with the estimation process. It is also recommended that conventional mass balance checks be carried out to cross-check.

.wor File

This file is a MapInfo workspace and is created for every simulation. It is named XXX.wor (XXX = xp project name) and is written to the project folder. The workspace contains all GIS layers used as input to the simulation, and is an excellent way of ascertaining which GIS layers were used to set up a model, particularly large models with many GIS inputs.

The .wor file when opened in MapInfo simply opens the .tab layers. No Map or Browser windows are automatically opened. The file may also be viewed in a text editor.

2D Errors - The messages.mif File

The polygons and connectors created may have violated some of the required conditions for 2D modeling. In this case the 2D model may not run and become unstable. The messages and other information are written to a file called <.xpswmm filename>_messages.mif located in the project folder. These messages are georeferenced and can be viewed in the Diagnostics layer.

See Diagnostics for instructions on managing the display of messages files.

 


To modify the display of the diagnostic messages

  1. Right click on the name of the messages.mif file in the layer control panel and select Properties

  2. On the Drawing Attribute tab, edit the display properties of the georeference point

  3. On the Data Tab modify the display of the error messages

 Typical messages with their meaning and suggested solutions are given below.

Diagnostic Message

Explanation

Solution

ERROR 2061 - Could not find a connection at the end of HX line with name

The end of the 1D/2D interface (HX code) must have a connector. FIX THIS FIRST!!!

Make sure both ends of the 1D/2D interface string have a connector to a 1D node

ERROR 2024 - Could not find a 1D node connected to EC or CN line with name


Node - Link invert to 2d must be selected

ERROR - Connection object unused or not snapped to 2D HX or 2D SX object.

The 1D/2D connector no longer connects to the 1D/2D interface

Delete the connector and create a new one so that the snap will work

ERROR - Unresolvable connections to 1D Nodes: Node15, Node15, Node11, Node25

The 1D/2D connector no longer connects to the 1D/2D interface

Delete the connector and create a new one so that the snap will work

CHECK - Repeat application of HX boundary to 2D cell ignored

Two of the 1D/2D interfaces lines go through one cell

Turn on the 2d domain so you can see the cells. Move or Delete one of the 1d/2d interface lines.

ERROR - ZC level of 157.6 at 2D HX cell is below interpolated node bed level of 157.9

The 2d cells that form the banks along the 1D/2D interface must be higher than the nodes inverts of the 1D channel.

Test levels along the 1D/2D interface are interpolated from the invert levels of the connected nodes. The cell centers along the interface string must be above these test levels.

First, check the invert levels of the nodes you have connected to the 1D/2D interface.
If these are correct then consider adding more 1D/2D connectors so that the 1D/2D interface line has more points to interpolate between.
Next, check if the 1D/2D interface has been drawn through a low point and not stayed up on top of the bank (i.e. lower than the nodes)


if this error is at a cell centre that you thought was inactive then check the boundaries and the 50% rule. (see What makes a cell active?)

Adjust the inactive/active boundary. Add the 2dactive and inactive layers on with the 2d domain to see where the active cells are.

ERROR 2132 – Node is duplicated or does not exist in external 1D domain

A multilink is connected to 2D and is using Water Level Lines – Water Level Lines cannot be used with Multilinks

Delete the Water Level Line markers/arrows for the given multilink



What makes the cell active?

Default mode is changed by Active and Inactive area polygons

If 50% of a cell side is on the active side then the cell is active

Cannot move 1D/2D connector and get a snap onto the interface even though selectable and snap is turned on?


delete the connector and create a new one

It just will not run 2d


check the *.2dlog file for error messages if not try the *.tlf file

mif errors in *.2dlog and/or *.tlf file

the polygons in XPSWMM are not valid. Most likely small polygons have been created by mistake

look through the *.mif files with a text editor to find one that ends with odd characters. Check the file name to find out the data type. Only show this one layer in XPSWMM and use the select rectangle to select all of the polygons. Now that they are all selected, small unwanted polygons may appear. Delete these.

Too many messages are shown

you can limit the number of messages

Right click in layer control on the diagnostic file and change setting on data tab

SMS (Map) Output (.dat Files)

XPSWMM and XPStorm produces the files described in the table below.  xp .DAT files are now wrapped in a new XMDF format that is on by default,  and contains all the results selected by the user. The range of .dat files is controlled by the Map Result Types selection under 2D Job Control.  

The envelope of maximum and/or minimum values is available for some output types using the options in Map Result Types.  Minimums are assigned a time of –99999.0 and maximums a time of 99999.0. For water level output (_h.dat), the time at which the maximum water level occurred is also provided and assigned a time of 99999.1.

Note that for some data types such as velocity (_V.dat), the minimum and maximum output is the velocity when the minimum or maximum water level occurs (not when the minimum or maximum velocity occurs). This is because high velocities can briefly occur during the wetting process, and are not particularly representative of the peak velocity.

The SMS super (.sup) file containing the various files and other commands that make up the output from a single simulation. Opening the .sup file in SMS opens the .2dm file containing the model mesh and the any of the _h, _V, _q and _d .dat files. Other .dat files (whether from the same simulation or another simulation) are opened in SMS using File, Open. If the .sup file is not used to open the results, the .2dm file must be opened before opening any .dat files. If opening .dat files from another simulation, the number and location of non-land (Code ≠ 0) cells must be the same in both simulations. The SMS Data Calculator feature is useful for comparing the results of different simulations.

SMS (Map) Output Files

Suffix & Extension

Description

Flag

.sup

SMS super file containing the various files and other commands that make up the output from a single simulation. Opening this file in SMS opens the .2dm file and the _h, _V, _q and _d .dat files.

n/a

.2dm

An SMS two-dimensional mesh file containing the information on elements’ and nodes’ location, shape and the connectivity between elements and nodes. It also contains information on the different materials and cell codes (display the SMS mesh materials). Note that the elevations (bathymetry) in the .2dm file only show the ZH values (ie. top right corner of cell). Other Z#points cannot be shown (as yet).

Additional information for each element that is not used by SMS, is used by the utility program sms_to_mif.exe to convert the .2dm file to a GIS layer.

In the TUFLOW .2dm’s present format, nodes only occur at the corners of the cells (elements). The bed elevations at the nodes are set to the ZH values. All hydraulic parameters are interpolated to the nodes (cell corners).

n/a

_d.dat

SMS scalar data file containing water depths at the nodes (cell corners). The depths are calculated as the interpolated water level at the nodes (see _h.dat below) less the ZH value. The interpolated water level may occasionally lie below the ZH value, in which case a negative depth may result which is set to zero by default (see Zero Negative Depths in SMS). Both maximum and minimum output is available.


d

_E.dat

SMS scalar data file containing the energy levels at the element nodes (cell corners). The energy levels are based on the interpolated water levels calculated at the cell centers plus the dynamic head (V2/2g). Due to the interpolation, occasionally an “increase” in energy can occur - an alternative approach to correctly display energy without interpolation is planned for a future release.
Maximum and minimum energy levels were incorporated in Build 2003#03#AE. The maximum and minimum output is for when the maximum and minimum water level occurs.

E

_F.dat

SMS scalar data file containing the Froude Number at the element nodes (cell corners). No maximum and minimum output is available at this stage.

F

_h.dat

SMS scalar data file containing water levels at the nodes (cell corners). The water levels are interpolated from the water levels calculated at the cell centers. Both maximum and minimum output is available.

h

_q.dat

SMS vector data file of unit flow (m2/s, i.e. flow per unit width) at the nodes (cell corners). The resulting flow vector is calculated from the surrounding u and v-points and the depth determined in _d.dat above.

Unit flow may also be used as a measure of flood hazard (ie. velocity by depth or VxD).

Note: The maximum and minimum unit flow output (times 99999.0 and #99999.0) is for when the maximum and minimum water level occurs.

q

_R.dat

SMS scalar data file containing a number indicating the flow regime. The value is 0 (zero) for normal (sub-critical flow with momentum); greater than 1 for upstream controlled friction flow (e.g. supercritical flow); #1.5 for broad-crested weir flow; and –1 for submerged flow through a flow constriction. No maximum and minimum output is available at this stage.

R

_SS.dat

The net source/sink inflows. Note the flow rate for a cell is shown at the ZH point (top right of the cell).

SS

_t.dat

SMS scalar data file containing the variation in eddy viscosity coefficient. This is useful for checking the Smagorinsky coefficient values. No maximum and minimum output is available at this stage.

E

_V.dat

SMS vector data file of flow velocities at the nodes (cell corners). The resulting velocity vector is calculated from the surrounding u and v-points.

Note: The maximum and minimum velocities (Times 99999.0 and #99999.0) are when the maximum and minimum water level occurs.

V

_Z1.dat

Flood hazard category based on the Australian NSW Floodplain Management Manual. The output is a number from 1 to 3 as follows and as illustrated in the figure below.

1 Low Hazard

2 Intermediate Hazard (dependent on site conditions)

3 High Hazard

Note: The maximum hazard value (Time 99999.0) is monitored throughout the simulation and is not necessarily when the maximum water level occurs as with some other output.

Z1

_Z2.dat

Flood hazard mapping approach – to be documented.

Z2

_Z3.dat

Flood hazard mapping approach – to be documented.

Z3

_ZH.dat

Elevations at the cell corners (ZH points). This information is already contained in the .2dm file, however, this option is useful if the model’s bathymetry varies over time if using variable geometry (VG) boundaries or for morphological modeling. No maximum and minimum output is available at this stage.

ZH

Delay Loading 2D Results

This option allows the user, upon opening a model, the choice of delaying the loading of 2D results or not. The “Load 2D Results?” dialog has the following options. If the results were created in a previous version, they will have to be converted to XMDF, which can take some time.

The “Remember my preference” option, if checked, will store the user’s preference to open (Yes) 2D results each time a model with 2D results is opened. The “No” option will indicate that 2D results will not be opened each time a model with 2D results is opened. If the “Remember my preference” is not checked, the second dialog will appear each time a model is opened.

Should the user change preferences, the options are stored in .ini file, in two fields:

  1. LOAD_2D_RESULTS_ON_MODEL_LOAD

  2. DISPLAY_2D_RESULTS_LOAD_QUESTION

These fields have been added to the Application Settings dialog, so they can easily be changed without having to manually edit the .ini file, or restart the application.

 Tools -> Applications Settings ->CONFIG:

  1. Display 2D Results Query – if checked, will cause the “Load 2D Results?” dialog to open when opening a model.

  2. Load 2D Results on Start – if checked will cause the 2D results to load when opening a model, if unchecked, 2D results will not load.

2D Animations and Graphs

2D model results can be displayed in animations and graphs. Results may be exported as maps or csv data files.

The results graphics may be accessed and managed with the Layer Control Panel.

Click on the icon in the Toolstrip to toggle the display of the Layer Control Panel. Double click on the Layer Control Panel title bar to toggle from fixed position to floating. Expand the Results folder to access the editing and display controls.

Check the box in front of the Reporting layer the results layer to display the 2D results. If the 2D model has been solved of the video controls are displayed.

The results groupings are described below. 

1D Flood Maps

Similar to the format of the 2D results maps, the 1D Flood Maps option will represent 1D open channel conduit results as flood extent depth maps. These flood maps are created by interpolating the 1D open channel conduit results with an *.xptin surface by checking the visibility box next to the 1D Flood Maps layer. A user can review the interpolated 1D results maps either at each saved time interval (as specified in the Hydraulic Job Control) or as a maximum depth/extent which occurs during the simulation. The 1D Flood Map results can be saved as an *.avi video file.

TIN restriction: The 1D Flood Maps are generated on only one TIN, if there are several TINs in the model, the algorithm will use the first TIN available.

 

Input parameter: Search radius. This is the maximum distance in which a TIN vertex looks for flood reference points on the river network. Possible reference points are:

  • Nodes that are incident to a natural channel
  • Bend points of a natural channel
  • The intersection point of a natural channel segment and the perpendicular on it through the TIN vertex

The default search radius is 75m.

Processing handling: There is a preprocessing required to display the 1D Flood Maps (all TIN vertices have to find their flood reference points). Depending on the size of the TIN this can take up to several minutes. The preprocessing is performed when the ‘1D Flood Maps’ button is selected and there are hydraulic results available. A progress bar gives an estimate on how long the process will still take.

To prevent unnecessary later executions of the preprocessing (the ‘1D Flood Map’ button is toggled off and on) an internal flag is set to Indicate that the preprocessing was already done. The flag is reset on one of the following actions

  • Resolving the model
  • Changing the search radius

Algorithm: In the preprocessing the flood reference points for each TIN vertex are computed. For possible reference point types see above (Input Parameter). A flood reference point has to lie within a distance of <searchRadius> from the TIN vertex. The maximum number of flood reference points that a TIN vertex can have assigned to is 16. Consider the coordinate system with the TIN vertex as origin. For each quadrant we assign the maximum number of 4 flood reference points to the TIN vertex. If in one quadrant there are more than 4 reference points within a distance of <searchRadius>we assign the 4 closest points. We also compute the highest TIN elevation on the straight-line segment between each TIN vertex and reference point.

Depth retrieval: For each time step and each flood reference point the water elevation is retrieved from the 1D simulation results. For nodes it will simply be the node elevation and for points that lie along a natural river segment the water elevation will be determined on the ground elevation of the reference point, the location of the point relative to the U/S and D/S node of the river segment it’s lying on and eventually using linear interpolation on the water elevation values of the U/S and D/S node. A flood reference point can only “carry” water to a TIN vertex assigned if the water elevation at the flood reference points exceeds the highest TIN elevation on the straight-line segment from the reference point to the TIN vertex. Eventually, the water elevation of the TIN vertex is determined by an inverse-distance weighting scheme on the water elevations of all reference points.

Disclaimer: Please note that the 1D Flood Map results are (as stated above) an interpolation of 1D node results with an *.xptin – this is NOT a 2D results set. A fully dynamic 2D model will typically give significantly more accurate flooding extent results. In the case of suspicious results (meandering channels) occurring with the use of the 1D Flood Maps option the flood map should either be split into several parts or 2D fully dynamic simulation should be used.

2D Vectors

On the Layer Control Panel check the box for the 2D Vectors layer to display vector results.

Select the 2D Vectors layer. Right click to launch the pop-up menu.

 

Select Flows (ft²/s or m²/s – discharge per unit width) or Velocity (ft/s or m/s) results to be displayed as vectors during animations.

Select Export the Current Results Time Step to generate a text file of results.

Select Export Results to generate a GIS file.

Select Properties to adjust the display properties of the selected parameter.

Export Current Results Time Step

The results of the current time step can be exported to a comma separated variable (csv) text file. To generate the file, place the cursor over the 2D vectors or the 2D Maps line in the Layer Control Panel and right click.

Select Export Current Results Time Step. A Windows Explorer dialog will open. Navigate to the desired folder location, enter the file name, and click on Open.

A text file will be generated. The first line indicates the time step. The second line contains column headers. The results for each cell in the 2D Area Extent begin with row 3.

 

The first two columns are the counters for the 2D Area Extent Grid.

The x and y columns are the coordinates of the cell. Zero values indicate that there is no 2D Active Area in the cell.

The contents of the fifth column depend on which 2D Maps radio button is checked. The contents are the center cell value of:

Water Depth (ft or m),

Water Elevation (ft or m), or

Hazard = depth × velocity (ft²/s or m²/s)

where:

velocity = the vector sum of the x and y velocity components

velocity = SQRT (V²x + V²y)

The sixth and seventh columns depend on which 2D Vectors radio button is checked. The contents are the magnitude of the x-component (across the left and right sides) and the y-component (across the bottom and top sides) of:

Flow (ft²/s or m²/s – discharge per unit width) or

Velocity (ft/s or m/s).

The maximum values for each cell may be exported by clicking on the Maximum Values button on the 2D Results Video Controls tool bar.

Export Results

The results of the selected mapped variable can be exported to several different file types, including GIS (shape file), mapinfo (*.mid/*.mif files) or as an ESRI Grid (*.asc file). To export a results set highlight the 2D Maps layer and select Export Results from the pop-up menu.

Select the desired Output File Format from the drop list. Click on Export. The 2D results sets can be given a filename in version 2013 and beyond.

xp then reports the information regarding the exported file.

ESRI Grid File export option:

The sample points that are written to an ESRI grid file (*.asc) are ALWAYS axis aligned. This is important to note when exporting a results set for use outside of the software.

Regarding the algorithm - First, the rectangular, axis-aligned, minimum bounding box is computed that contains all cells with valid results. In the case of the 2D grid being axis-aligned as well the edges of this bounding box will be co-aligned with 2D cell borders, i.e. the 2D results values will line up exactly with the ESRI Grid file sample points.

The default stepping for the sample points that get exported is #2DCellWidth/2 starting from the bottom point of the bounding rectangle shifted by #2DCellWidth/2. The values for the sample points are derived by bilinear interpolation on the 4 corner values of the 2D grid cell the point is lying in.

Now, if you have a rotated 2D grid, the proceeding is exactly the same, i.e. the exported points are still sampled in an axis-aligned manner within the axis-aligned bounding rectangle. That means in this case the sample points will not be aligned with the 2D grid as the ESRI Grid file cannot accommodate axis rotation while the xp model can.

One option is to decrease the step size in which the sample points will be reported to a value less than #2DCellWidth/2. That will give you a more detailed result; however, it will also increase the size of the ESRI grid file. Internal grid sampling correction has been implemented as part of the export procedure which greatly increases the appropriateness and accuracy of the sampled results values if the 2D grid is rotated though reporting differences may still occur for significant grid rotation or drastically varying export grid size (relative to the source grid size). That being said, the differences are typically very small and any differences are a shortcoming of the ESRI Grid (*.asc) file format.

Properties

The display properties of vector and map results may be adjusted. 

Vector display properties

Fill Colors

Flows and Velocity results may be displayed will cell color coding over the simulation period. Highlight the Flows or Velocity row in the Layer Control Panel, right click. Select Properties then click on the Fill Colours Tab. Use this dialog to customize the display.

Check the radio button corresponding to the selected Fill Style: a ramp of a colour mix, an intensity scale of a single, user defined color, or a single colour. When either of the last two options are selected a drop list will appear to allow for selection desired colour

When the Ramp Fill Style is selected, the Color Peg dialog appears to allow the user to defined style. The styles may be save as a .cip file and reloaded for later use.

Use the Reverse button to invert the colour style.

The histogram on the left side of the dialog indicates the range of values in the results. The display may be restricted to a user defined range.

Use the legends properties dialog to customize the legend for flow and velocity.

Arrows

Arrows (displayed as 2D Vectors) are used to show flow and velocity results over the simulation period. Highlight the Flows or Velocity row in the Layer Control Panel, right click. Select Properties then click on the Arrow tab. Use this dialog to customize the display of the arrows.

The arrow head may be displayed with a fixed or scaled size. Check the box to display a filled arrow head.

The total length of the arrow may be displayed with a fixed length, scaled length or with defined range (in mm).

The shaft width may be displayed as fixed or scaled.

The histogram on the left side of the dialog indicates the range of values in the results. The display may be restricted to a user defined range.

Use the legends properties dialog to customize the legend for flow and velocity.

Labels

The values of Flows, Velocity, Water Depth, Water Elevation and Hazard during the simulation period may be displayed. Highlight the selected parameter row in the Layer Control Panel, right click. Select Properties then click on the Labels tab. Use this dialog to customize the display of the labels.

The display of the Results Values and/or Number for each 2D cell l at the simulation time steps can be toggled off/on with the check boxes. Select the font and skip fill in box to enhance the readability.

The display of the cell number can be toggled off/on. Select the font to enhance the readability.

The histogram on the left side of the dialog indicates the range of values in the results. The display may be restricted to a user defined range. Values outside of the range are left blank.

Maps Display Properties
Fill Colors - Maps

Water Depth, Water Elevation and Hazard results may be displayed will cell color coding or contouring over the simulation period. Highlight the Flows or Velocity row in the Layer Control Panel, right click. Select Properties then click on the Fill Colours Tab. Use this dialog to customize the display.

Check the radio button corresponding to the selected Fill Style: a ramp of a colour mix, an intensity scale of a single, user defined color, or a single colour. When either of the last two options are selected a drop list will appear to allow for selection desired colour

When the Ramp Fill Style is selected, the Color Peg dialog appears to allow the user to defined style. The styles may be save as a .cip file and reloaded for later use.

Use the Reverse button to invert the colour style.

Use the drop lisp under Display to select a filled and/or contour display.

The histogram on the left side of the dialog indicates the range of values in the results. The display may be restricted to a user defined range.

Use the legends properties dialog to customize the legend for Water Depth, Water Elevation and Hazard. 

Contours

Water Depth, Water Elevation and Hazard results may be displayed will cell color coded contouris over the simulation period. Highlight the Flows or Velocity row in the Layer Control Panel, right click. Select Properties then click on the Contours Tab. Use this dialog to customize the display.

Check the radio button corresponding to the selected Style: a ramp of a colour mix, an intensity scale of a single, user defined fill colours, or a single colour. When either of the last two options are selected a drop list will appear to allow for selection desired colour. When a selection is made, the corresponding drop list appears.

In the Contour Steps box, select either the number of contours or the contour interval. Enter the value in the box next to the drop list.

Enter the desired pen width and then select units of pixels or millimeters.

The histogram on the left side of the dialog indicates the range of values in the results. The display may be restricted to a user defined range.

Use the legends properties dialog to customize the legend for Water Depth, Water Elevation and Hazard.

Labels

The values of Flows, Velocity, Water Depth, Water Elevation and Hazard during the simulation period may be displayed. Highlight the selected parameter row in the Layer Control Panel, right click. Select Properties then click on the Labels tab. Use this dialog to customize the display of the labels.

The display of the Results Values and/or Number for each 2D cell l at the simulation time steps can be toggled off/on with the check boxes. Select the font and skip fill in box to enhance the readability.

The display of the cell number can be toggled off/on. Select the font to enhance the readability.

2D Maps

On the Layer Control Panel check the box for the 2D Maps layer to display map results as a color coded fill or as contours.

Select the 2D Vectors or 2D Maps layer. Right click to launch the pop-up menu.

 

The default 2D Map Result Types to be displayed as maps during animations are Flow, Velocity, Water Depth, Water Elevation, and Hazard results.

Water Depth (ft or m),

Water Elevation (ft or m), or

Hazard = depth × velocity (ft²/s or m²/s)

where:

velocity = the vector sum of the x and y velocity components

velocity = SQRT (V²x + V²y)

The full list of available 2D Maps output options is listed in the 2D job control, under Map Result Types.

Select Export the Current Results Time Step to generate a text file of results.

Select Export Results to generate a GIS file.

Select Properties to adjust the display properties of the selected parameter.

The 2D Results Maps can be used in conjunction with Scenarios, or Global Storms. The maps can then be viewed in a ‘stacked’ format for comparison. The properties of each map can be adjusted individually for ease of comparison.

 After closing the file, changes made to the 2D results map properties will not be maintained for child scenarios. 

Time Series Output

Highlight the Time Series Outputs layer and right click. Select either Show Flow Graphs or Show Head and Velocity Graphs from the popup menu.

Time Series Output Head and Velocity Points

The Time Series Output Head/Velocity point layers are used to manage time series plots of the HGL (ft or m) and Velocity (ft/sec or m/sec) referenced to user defined locations in an Active 2D Area of the model. Output points must be defined before the model is calculated.

To define a Head/Velocity output point

  1. Right click on the Time Series Output Head/Velocity layer in the Layer Control Panel and select Define Plot Output Point.

  2. The cursor will appear as an arrow and a point indicator.

  3. Mover the cursor to the desired location in the model and click.

  4. Enter the label in the pop up dialog.

  5. Click OK.

To modify the appearance of output points and labels in the network view

  1. Right click on the Time Series Output Head/Velocity layer in the Layer Control Panel and select Properties.

  2. Select the Drawing Attributes tab in the Head/Velocity dialog to modify the appearance of the point.

  3. Select the Attributes tab in the Head/Velocity dialog to modify the font and color of point labels and the appearance of the time series chart

To move an output point

  1. Make sure the Time Series Output Head/Velocity layer is visible, unlocked.

  2. Move the cursor to a point in the network view. The cursor will change to a 4-arrowed cross.

  3. Hold the left button down and drag the point to the desired location. Release.

To display the times series charts

  1. Highlight the Time Series Outputs in the Layer Control Panel.

  2. Right click and select Show Head and Velocity Graphs from the popup menu.

To obtain Output Point data as a text file

  1. While viewing the chart, right click and select Export Dialog from the pop up menu. Select the Text/Data Only radio button and then select the destination, or

  2. In the project folder, locate a file named XXXX_PO.csv where “XXXX” is the XPSWMM file name. This is a comma separated variable text file containing time series results for Output Points and Output Lines. Note that the results are in m for points and m³/s for lines regardless of the project settings.

To import Head/Velocity from GIS file

  1. Right-click the Head/Velocity layer in the Layer Control Panel and select Import From GIS File.
  2. In the Import GIS File dialog, click the ellipsis and locate the file to import. Click Open.
  3. Click Import.
  4. In the Results Line Import Properties dialog, you have the option to render the Result Line Names to:
    1. Default Name - The name will be rendered as Point 1, Point 2, Point 3, etc. in the Layer Control Panel.
    2. Set Result Line Names From Attribute Data - The name will be rendered based on the selected attribute data from drop-down list.
  5. Click OK.


Time Series Output Flow Lines

The Time Series Output Flow Line layers are used to manage time series plots of flow across user defined cross sections (constructed as polylines) in the Active 2D Area of the model.

Flow is reported as the total discharge (ft³/s or m³/s) perpendicular to the cross section. Flow is considered positive when moving in the left hand direction from the view point of the first vertex looking towards the last vertex. Output lines must be defined before the model is calculated.

To define an Output Line

  1. Right-click the Time Series Output Flow line in the Layer Control Panel and select Define Flow Line.

  2. The cursor will appear as an arrow with a polyline indicator.

  3. Mover the cursor to the first vertex location in the model and click.

  4. Continue adding vertices. Double click on the last vertex.

  5. Enter the label in the popup dialog.

To modify the appearance of output lines

  1. Right-click the the Flow line in the Layer Control Panel and select Properties.

  2. Select the Drawing Attributes tab in the Flow Lines dialog to modify the appearance of the line.

  3. Select the Attributes tab in the Flow Lines dialog to modify the font and color of output lines labels.

To move an output line

  1. Make sure the Time Series Output Flow layer is visible and unlocked.

  2. Move the cursor to a line in the network view. The cursor will change to a 4-arrowed cross. If the cursor is located on a vertex, the vertex is moved. If the cursor is located on the line between vertices, the entire polyline is moved.

  3. Hold the left button down and drag the vertex or line to the desired location. Release.

To display the times series charts

  1. Highlight the Time Series Output Flow line in the Layer Control Panel.

  2. Right-click and select Show Flow Graphs from the popup menu.

To obtain Output Line data as a text file

  1. While viewing the chart, right click and select Export Dialog from the pop up menu. Select the Text/Data Only radio button and then select the destination, or

  2. In the project folder, locate a file named XXXX_PO.csv where “XXXX” is the XPSWMM file name. This is a comma separated variable text file containing time series results for Output Points and Output Lines. Note that the results are in m for points and m³/s for lines regardless of the project settings.

To import Flow from GIS file

  1. Right-click the Flow layer in the Layer Control Panel and select Import From GIS File.
  2. In the Import GIS File dialog, click the ellipsis and locate the file to import. Click Open.
  3. Click Import.
  4. In the Results Line Import Properties dialog, you have the option to render the Result Line Names to:
    1. Default Name - The name will be rendered as Point 1, Point 2, Point 3, etc. in the Layers Control Panel.
    2. Set Result Line Names From Attribute Data - The name will be rendered based on the selected attribute data from the drop-down list.
  5. Click OK.

Legends

The Legends Properties dialog is used to adjust the legends for 2D results and the timestamp for the animations. It is accessed in the Results section of the Layer Control Panel.

Check the Visible box to display legends. To enable the legends properties, right click the Legends layer and select "Properties." 

Select the tab corresponding to the results layer for which the legends properties are to be set.

Click on the radio button corresponding to the selected Background.

Pick the legend location from the drop list. All distances are measured to the top left corner of the legend.

  • The World Coordinates option uses the x and y coordinates of the model. Legend is fixed to specified location. Coordinates of a point are obtained from the status bar.
  • Screen relative is the distance from the upper left corner of the screen. Legend will float with panning.
  • To Left, Top Right, Bottom Right, and Bottom Right will place the legend in a corner of the screen. Legend will float with panning.

Edit the Title field, set the Font and Color for the legend title. 

Set the Font and Color for the numerical Values in the legend.

To adjust the timestamp settings:

  1. Select the timestamp tab. 


  2. Check the Display Results Timestamp to enable the appearance of the timestamp on the network view.
  3. Click on the Font tab to adjust the font of the timestamp display.
  4. Click on the Color tab to adjust the color of the timestamp display.

2D Times

The 2D Times section by default contains the results of Time to Peak V and Time to Peak h for the simulation. If the Time to Inundation - Duration of Inundation option is selected within the 2D Job control then these result options will also be shown. All 2D Times results are reported as time in hours.

To export any 2D Times result set, select the given layer, then right click to launch the pop-up menu.

Select Export the Current Results Time Step to generate a text file of results.

Select Export Results to generate a GIS file.

Select Properties to adjust the display properties of the selected parameter.

Diagnostics

Diagnostics are text and GIS files use to identify issues with 2D models.

To open a text file:

  1. Right click on the Diagnostic layer in the Reporting section of the Layer Control Panel.

  2. Select either Show 2D log file or Show 2D error messages from the pop-up menu.

To add a diagnostic GIS file:

  1. Right click on the Diagnostic layer in the Reporting section of the Layer Control Panel.

  2. Select Add Diagnostic File… from the pop-up menu.

  3. In Windows Explorer, navigate to a XXX_messages.mif file. XXX is the name of the XPSWMM model. This file is usually located in the ..\2D\Results\Log folder.

  4. Click on open.

  5. xp reports the number of messages read.

See the message.mif file for guidance on resolving 2D modeling issues.

Other help topics relevant to 2D models