xpswmm/xpstorm Resource Center xps

The 2D Job Control settings dialog has a tree control in the left panel. Use this control to display the desired section in the right panel. To load the 2D Job Control settings dialog from the Configuration menu, click Job Control > 2D Model Settings. Alternatively, you can access this dialog using the 2D Job Control icon  in the toolbar.

This page contains the following topics:

General Settings

This dialog allows you to specify the settings that will be used to calculate 2D hydraulics.


2D Model Active - Allows you to activate the 2D model to calculate the 2D hydraulics on.

Initial timestep - The first timestep Heavily Parallelized Compute (HPC) will use for adaptive timestepping.

1D/2D Sync timestep - This applies to all grids when multiple domains are used. Different timesteps can be used by overriding the 1D/2D Sync timestep in each 2D Grid Extents. A normal starting value is the cell size divided by two for metric and divided by six for US Customary units.

Adaptive Timestepping - This allows for adaptive timestepping for 2D only models. These models only work when there are no 1D elements in the model. Adaptive Timestepping is always activated when XP2D Extreme is selected, and it is always disabled when XP2D Classic is selected.

Control Number Factor - This is activated when XP2D Extreme is selected. This is not applicable for XP2D Classic. Set a value between 0.001 and 1.199. The default value is 1.0. Typical range from 0.5 to 1.0.

XP2D Classic - By default, the XP2D Classic is selected. This setting will follow the export logic using the classic method. 

XP2D Extreme - When XP2D Extreme is selected, the solution scheme will be changed to HPC.

For the best performance with XP2D Classic and XP2D Extreme models, the use of a ESRI FLT binary format will produce the fastest 2D results.

When using XP2D Extreme, large xptin models should not be used as they create very large TIN formats for the 2D engine. This will generate a large lag time processing the terrain. Innovyze recommends that you use either the source data, or export the xptin to a grid format.

XP2D Extreme


    • CPU - This option allows the application to solve a 1D-2D model against multiple threads, which also works with Solve Manager, allowing the number of active simulation x threads not exceed the physical cores available for a model simulation. If you have selected CPU, you have to select the corresponding CPU ThreadsBy default, the CPU Threads field is set to two.
    • GPUThis option will only be available if you have Graphics Processing Unit (GPU) enabled license and an NVidia/CUDA-capable graphics card. Otherwise, the GPU option will be disabled. This option enables the GPU solver in your computer, which takes advantage of the parallel computing power of a GPU for faster processing of your model. Instead of computing values one cell at a time, this option allows you to compute the values of cells simultaneously, which leads to substantial increase in speed, especially for large models.


    • Grid - This option allows you to define the boundary of a domain in the 2D model. A grid with equal horizontal and vertical cell size and orientation extends over the polygon. For more information, refer to Grid Extents.
    • Quadtree - This option enables variable-sized grids using the Multiple Domain module that allows you to focus on detail where needed. This provides flexibility to reduce simulation memory and decrease computational speed. For more information, refer to Quadtree Extents and Quadtree and Sub-Grid Sampling FAQ.

Default Landuse Category - This is a drop-down menu that allows you to select the landuse. For the list of available landuses, refer to Global Database

Default Area Type - This option allows you to select to use Active Area or Inactive Area from the drop-down menu, when not specified by a polygon. Starting XPSWMM/XPStorm 2011, this is set to Active Area by default. Existing models keep their original setting. Cells outside of the polygon defining the grid extents are always inactive and cells inside the polygon are either active or inactive depending on this setting. 

2D models containing multiple domains are no longer permitted to solve with Inactive Area as the Default Area Type. Multiple 2D domain models should always use Active Area as the Default Area Type, and use appropriate grid extent polygons to define the domain extents, instead of large active area polygons.

Wet/Dry Depth - The minimum cell depth for a cell to be considered as wet in the 2D calculation.

Always use double-precision solver - This is the default solver when 2D Rain polygons are used.

Additional mass balance iteration - This option allows you to activate the additional mass balance iteration in the calculation.

Produce Check Files - When this option is selected, the 2D engine check files will be produced upon completion of the simulation. Setting this option off may be desired if you are performing the same simulation run several times with minor revisions and do not wish to review the check files for all model runs. 

When the Produce Check Files is selected, you have the option to write X1D check files to the map output by selecting the Write X1D Check Files button.

Produce ASC Map Output - This option allows you to produce the map output to GIS ASC format.

Inflow Capture

2D Inflow CaptureSelect this check box to specify the default method for simulating inflow from a 2D cell to a 1D linked node. If this option is selected, a user-defined power curve will be used. This is defined by the formula:

Q (cfs, cms) = coefficient × 2D cell depth (ft, m) ^ exponent

If this option is not selected, the application uses the Pre-2009 method, which is defined by the formula:

= Area of Manhole × (2D water depth – Node Spill Crest)/2D time stepb

  • Coefficient > 1
  • The inlet capacity setting at individual nodes may be defined with the 2D Inflow Capture setting in the Hydraulics Node dialog.
  • If the 2D Inflow Capture check box not selected, the application will use the Pre-2009 Method.

Viscosity Formulation

Type - The following options are available for specifying eddy viscosity for the 2D domains to approximate the effect of small-scale motions that cannot be modeled directly:

    • Constant - This method allows you to supply a constant value that will be 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). 
    • Smagorinski - This method is an approximation to the Smagorinsky formulation. This formulation is preferred when the cell size is similar or less than the depth.
    • Wu - This is the default and recommended formulation for XP2D ExtremeThis type is less sensitive to cell size and provides a better fit. The Wu formulation is not available for XP2D Classic.

Constant Coefficient - It is not recommended that a value other than 1 m²/s or 10.76 ft²/s be used for the constant viscosity formulations.

Smagorinski Coefficient - The Smagorinsky coefficient is typically between 0.06 and 1.0.

Wu 3D Components and Wu 2D Components - The recommended value for Wu 3D Components  is 7.0 while for Wu 2D Components, the recommended value is 0.

Testing by Barton in 2001 indicates that 2D schemes using very fine elements (less than 2 m) may have difficulty predicting correct flow behavior. Results from models with less than 2 m 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).

Model Output


The Map Results Output Interval specifies the time interval used for animation of 2D results.

The Time Series Output Interval specifies the time interval used for Time Series Output Head/Velocity Point or Flow Line timeseries.

Check the box next to Enable Mass Balance Output to specify that the cumulative mass error calculations are saved. A file XXX__MB.CSV (where XXX = project file name) is created in the results folder. The file contains information at each display time step. The time, inflows, outflows, volume, predicted volume error and the mass and cumulative mass errors as a percentage for all 2D domains and each individual 2D domain are tabulated. This output will be saved at the interval specified in the Mass Balance Output Interval field (Seconds).


When the Enable Time-to-Inundation Map check box is checked/selected 2D Times output maps of the Time to Inundation and Time of Inundation will be generated based on the supplied depth levels.

Map Result Types

Any of the following 2D results output types can be selected within the 2D Job Control > Map Result Types list by selecting the check box for the given output type. Note: units listed (U.S Customary; Metric)

  • Flow (ft3/sec; m3/sec)

  • Velocity (ft2/sec; m2/sec)

  • Water Depth (ft, m)

  • Water Elevation (ft, m)

  • Hazard (V*D)

  • Hazard (UK Formula)

  • Hazard Category (Australian NSW Floodplain Management Manual)

  • Hazard Category (Herbert River Flood Study)

  • Hazard Category (Tweed River Flood Study)

  • Hazard Category (Australian Guidelines)

  • Hazard Category (Melbourne Water - Property Safety Risk)

  • Hazard Category (Melbourne Water - Safety Risk in Roads)

  • Hazard Category (UK)

  • Bed Shear Stress (lb/ft2; N/m2) Detailed Bed Shear Equations

  • Courant Number

  • Energy

  • Froude Number

  • Mass Balance (Per Output Interval)

  • Mass Balance (Cumulative)

  • Manning's n

  • Flow Regime

  • Stream Power (lb/ft-sec; N/m-sec) Detailed Stream Power Equations

  • Sink/Source Inflow

  • Viscosity Coefficient

  • Bathymetry

  • Time to/Duration of Inundation (hours)

  • Minimum DT

Hazard maps (depth x velocity relationships) are calculated at each time step, similarly to the other 2D map results sets. This is important to note when reviewing the maximum hazard map values, these values are the true maximum hazard values which occur during the simulation, and not simply the maximum velocity which occurs multiplied by the maximum depth. Typically the maximum depth does not occur at the same time as the maximum velocity value and vice versa so a hazard value taken from these two unrelated values would be inappropriate and unrealistic. 


Water Levels

Initial Water Levels. The initial water level for all cells is set to the elevation specified.

Override Instability Levels. The default value water level used to detect instabilities is 1 m (3.28 ft) higher than the highest cell elevation of all cells (whether wet, dry or permanently dry). If the box is checked, the user specified value is used to detect instabilities – i.e. if this option is checked, when the depth of flow in any cell in the model reaches the specified level, the simulation will terminate and report instability at the location(s) where this depth occurred. This option is only to be used if you specifically wish to terminate a simulation if a given depth occurs, if this is not desired the Override Instability option should NOT BE USED.

2D Cell Checks

If 2D cells along the 1D/2D interface are lower than the Channel Bed:


Do nothing and allow the model to run with inappropriate levels where 1D and 2D are connected, erroneous results may be produced.

Report Only

Model will not run if this situation happens and errors will be produced which can be displayed using the diagnostics layer. These messages are also contained in the [model name]_messages.mif file.

Adjust (Raise if required)

Cell center elevation (Zc) will be raised up to the interpolated Channel bed level. This fixes the model from having the floodplain elevations below the lowest river cross section elevation.

If 2D cell at 1D node connection is above 1D Node Spill Crest the 1D node:


Do nothing and allow the model to run with inappropriate levels where 1D and 2D are connected, erroneous results may be produced.

Report Only

Model will not run if this situation happens and errors will be produced which can be displayed using the diagnostics layer. These messages are also contained in the [model name]_messages.mif file.

Adjust (Lower if required)

Cell center elevation (Zc) will be raised up to the node spill level. This fixes the model from having the manhole rim below the idealized ground elevation from the 2D grid.

Units are m (metric) and ft (US Customary). Node spillcrest levels can be set equal to the elevation of the DTM by using the generate ground elevations from TIN command on the Tools Menu.

Elevation Export Files

If the Include Additional mid/mif Elevation files is checked/selected, then upon solving the simulation the Cell Center elevations (Zpts) will be exported to *.mid/*.mif files for inspection external to the software interface. This is one way in which the Zpts can be expected to ensure that the 2D Grid Cells are appropriately representing the topographic surface. These files could also be used to create a DTM representing exactly how the 2D engine “sees” the data.

Folder Options

This dialog allows the user to specify where 2D data and results are stored. If unchecked, the results are written to the same folder as the .xp file.

Advanced Settings

The Advanced User Settings allows you to incorporate specific additional configuration commands to the 2D engine.

The Control File section allows configuration commands to be added to the Tuflow Control file (*.tcf). In order for commands to be applied to the engine the associated Flag will need to be selected.

PRE-2013 and earlier are no longer supported in XPSWMM/XPStorm 2018.2.1 and later.
Only one *.tgc file per 2D domain is specified within the *.tcf file.

The Geometry Control File section allows specific commands to be added to the Tuflow Geometry Control file (*.tgc). The top or bottom ordering option allows for the sequential application of commands. These commands in the *.tgc file are applied in sequential order, therefore, it is possible to override previous information with new data to modify the model in selected areas. This is very useful where a base data set exists, over which areas need to be modified to represent other scenarios such as a proposed development. This eliminates or minimizes data duplication.

This option is not typically recommended as the Scenario Manager is a robust tool which can allow numerous model designs or scenarios to be simulated, for both the 1D and 2D portions of the model.

For *.tgc Read GIS commands that require only one attribute (e.g. Code, Mat, Soil, GWL, GWD, IWL, CnM, WrF, FLC, CWF, SRF, Zpt), this attribute no longer needs to be the first attribute. If the attribute is not in the first position field, the position can be specified by including it as an argument before the GIS filename.

Creating Empty using Control File

In many cases, users might want to leverage external data files within the XP2D and XP2D Extreme Engine.  In this case, XP2D can generate empty file using the Advanced settings.

To enable the creation of Empty GIS files

  1. Go to Configuration > Job Control > 2D Model Settings.
  2. Click the Advanced Settings tab.
  3. In the Geometry Control File section, click Insert.
  4. Select the checkbox under the Flag column.
  5. In the Parameter - type Write Empty GIS Files

    The Write Empty GIS Files command should be written as is.

    In the Value column, 

  6. In the Value column, enter ..\model\gis\empty | SHP

The value should represent the location to place the empty shape files. In this case the value ..\model\gis\empty | SHP should be written as is, which will provide the files in the folder relative to the current XP model location. When Check files is on, this will be in the \2D\Model\gis\empty folder.

For additional information, see the Tuflow Wiki 

Using Geometry Control File Feature to Add 2D Landuse Reference File

This functionality allows the defined 2D landuse polygon to be externally referenced by the numerical engine. By externally referencing a large model, as opposed to directly importing it into the application, the save and analysis times will be significantly faster. This option is recommended when your model contains more than 50,000 vertices.

To externally reference a 2D landuse polygon:

  1. Go to Configuration > Job Control > 2D Model Settings.
  2. Click the Advanced Settings tab.
  3. In the Geometry Control File section, click Insert.
  4. Select the checkbox under the Flag column.
  5. In the Parameter column, type READ GIS MAT.

    The READ GIS MAT command should be written as is.
  6. In the Value column, enter the location and the filename of the GIS file.

    The GIS file should be located in the root folder as there is a limit in the number of characters for this column.
  7. In the Position, select from the drop-down list. The available positions are:
    • Top
    • After Surface
    • Bottom

  8. Click OK
  9. In the Layers Control Panel, verify that the added 2D landuse file is under 2D Landuse Reference


This dialog is used to define the geographic projects for all GIS input and output.

Header Delimiter specifies the field delimiter for the Header Projections input string

Header Charset specifies the character set for the Header Projections input string

Click the Load from Mapinfo MIF file to upload this information.

Surface and Sampling


Use DTM - By default, the Use DTM option is selected. The DTM surface that will be used during the 2D simulation will be the *.xptin file that have been specified in the DTM Layer

Use grid file for topography - A grid file can be specified by selecting the User grid file for topography option and browsing to the desired file (*.asc, *.flt, *.txt). In this option, no *.xptin is required to be loaded into the software interface in order to solve the 2D model. This is the recommended option when using XP2D Extreme.

Sub-Grid Sampling

Sub-grid sampling (SGS) uses curves representing the sub-2D-cell terrain data of the DTM surface or grid file. This results in a better resolution when viewing the output of your simulations. The SGS option is enabled when XP2D Extreme is selected in the 2D Job Control General Settings.


  • XP2D Extreme needs to be selected on General Settings when Use DTM is selected, and Sub-Grid Sampling is selected. The application will export the xptin to LandXML and a Sample Distance is required.
  • If Use grid file for topography is selected, Sample Distance is not required as the underlying resolution will be used. For example, a three foot resolution ESRI FLT will be the sample distance regardless of the cell size. If you want to speed up the sample distancing, some multiple of the underlying terrain should be used.

Enabled - Select this check box to enable SGS in the calculations.

Depth Interpolation Approach - Select from the following options:

    • Average - Uses the average value assigned to the cell center and the cell corners from the SGS sampling.
    • Exact - Calculates the depth using the cell center and cell corner elevations that would be sampled at their respective locations if SGS was not applied. By default, this is selected.
    • Median - Uses the median elevation for the cell.
    • Minimum - Uses the minimum value, i.e. the map output shows the maximum depth within a cell or around a cell corner.
    • Percentile - Uses an elevation based on the specified set percentile.

Sample Distance - The sample distance (in meters or feet) to be used for the grid at which the datasets are sampled.

SGS Map Extent Full - The extent at which SGS will be applied in the 2D simulation. By default, this is set to Water Level. The available options are:

    • Water Level
    • Water Level + Velocity
    • Water Level + Velocity + Hazard

For more information about the recommended settings, refer to XPSWMM and XPStorm 2020.1 Quadtree and Sub-Grid Sampling FAQ.