The Calibrate Model command launches a dialog box with a set of tools for automated calibration of the model. 

The Calibration module is an option that may be enabled from Innovyze.  This module is no longer supported.

This module facilitates automated calibration by interfacing XPSWMM with PEST , a non-linear parameter optimization engine. The sum of squared differences between modeled results and observed or target results is minimized in the weighted least squares sense. For example the difference between many points on a measured outfall hydrograph and a computed outfall hydrograph can be minimized to yield a high degree of fit.

The PEST engine accomplishes this by taking control of your model. It will rerun the model with updated input data based on sensitivity gradients foe all of the Parameters selected by the user. These calibration parameters can be bound to reasonable engineering limits and the estimated parameter values can then be imported as the final calibrated model.

Clicking the Calibrate button launches the calibration process by sending the generated control file to the PEST engine designated in the SWMXP.INI file. Calibration of the model must follow the generation and checking of all of the template files, instruction files, and PEST control file.

Observation Table

This table is used to store each observation with its measured and computed value. The observation ID’s will become automatically loaded into the Instruction File and the PEST Control File. The following functions operate on the table. The parameters to be used in the calibration are entered using the Parameters button and execution commences when Calibrate is selected.

    • Row. The row number for the set of observations contained in the observation table.
    • Observation Id. The unique alphanumeric 4 character ID for the observation. This observation ID will be used in the instruction file to pull computed results from the output file or other text file(s). The observation ID will also be used in the PEST Control File along with the Model Value.
    • Observation Value. The field, measured, or target value for the observation. PEST will optimize the model to predict this value by minimizing the weighted sum of squared difference of all observations in the least squares sense.
    • Model Value. The current model value that corresponds to the Observation ID. Typical sources of this information would be from Spatial Reports or User Defined Reports.

Graph

This button plots all of the observation data measured vs. Computed. Graphically a 45-degree line represents perfect correlation between measured and computed data.

Update Model Values

Loads the current “Model Value” computed from the last simulation run into the observation table. These results are compared to the observation value to determine the degree of fit.

Insert/Delete/Append Row

Inserts, deletes or appends a row in the observation table.

Calibration Library (LIBRARY.CAL file)

This file contains the current set of XPX variables that are enabled for automatic calibration. The columns within the file contains instructions for the software to locate object names and the location of the variable in the data file (.DAT). Not all XPX variables or XPSWMM parameters are suitable calibration parameters.

The LIBRARY.CAL file  contains the most common and most suitable XP variables that can be used for calibration. Click to expand the window below.

LIBRARY.CAL
#XPX_Name Layer Row Column Name_Locator

R_WAREA RUNOFF H1 6 2
R_WIMP RUNOFF H1 7 2
R_WIDTH RUNOFF H1 5 2
R_WSLOPE RUNOFF H1 8 2
R_CN RUNOFF H1 10 2
R_TC RUNOFF H1 11 2
R_SHF RUNOFF H1 12 2
R_IAFRACT RUNOFF H1 15 2
ROUGH EXTRAN C1 12 1
ROUGH TRANSPORT E1 7 1
ROUGH RUNOFF G1 9 1
PLC EXTRAN CX 5 1
GEOFF EXTRAN CX 7 1
RRAT EXTRAN CX 2 1
BARREL EXTRAN CX 8 1
R_WSTOR1 RUNOFF H1 11 2
R_WSTOR2 RUNOFF H1 12 2
R_IROUGH RUNOFF H1 9 2
R_PROUGH RUNOFF H1 10 2
R_PCTZER RUNOFF H1 4 2
R_WLMAX RUNOFF H1 13 2
R_WLMIN RUNOFF H1 14 2
R_DECAY RUNOFF H1 15 2
R_SUCT RUNOFF H1 13 2
R_SMDMAX RUNOFF H1 14 2
R_HYDCON RUNOFF H1 15 2
R_GDDLIM RUNOFF JX 5 -1
R_GDDFACT2 RUNOFF JX 7 -1
R_GDDPOW1 RUNOFF JX 6 -1
R_GDDPOW2 RUNOFF JX 6 -1
R_GDDPOW3 RUNOFF JX 6 -1
R_QCOEFF1 RUNOFF JX 8 -1
R_QCOEFF2 RUNOFF JX 9 -1
R_ERCOEFF RUNOFF JX 9 -1
R_EWASHPO RUNOFF JX 8 -1
R_COEFF RUNOFF JX 9 -1
R_WASHPO RUNOFF JX 8 -1
R_DLIM RUNOFF J2 4 1
R_DDFACT1 RUNOFF J2 6 1
R_DDPOW1 RUNOFF J2 5 1
R_DDPOW2 RUNOFF J2 5 1
R_QFACTD RUNOFF JX 5 -1
FMAX EXTRAN BB 7 0
QREF EXTRAN BB 15 0
HLOSS EXTRAN B2 8 0
CLOSS EXTRAN B2 4 0

The parameters are explained below: 

    • XPX_Name. The XPX variable name of the calibration parameter. R_ usually precedes RUNOFF variables T_ precedes most TRANSPORT variables. Consult the XPX references in the help or manual for more information on an individual variable.
    • Layer. The mode of XPSWMM to which the variable applies. This column also identifies the section of the data file to find the variable. The software uses this field to index to the appropriate section of the data file.
    • Row. The data file (.DAT) card or row label that contains the calibration parameter. These labels correspond to XPSWMM's data file structure and is very similar to that of EPA SWMM.
    • Column. The column where i is the integer representing which column in the data file will contain the calibration parameter. For example, R_WIDTH (the subcatchment width) is located on the H1 card of the data file in the 5th column. In other words it is the fifth item on the H1 line. The software uses this column to index to the correct location to place the PEST ID.
    • Name_Locator. Similar to the Column data the Name_Locator instructs the software where to find the object name on the data line. In a few cases such as RUNOFF water quality data the object name appears on a previous line. A value of -1 is used in this case. A value of 0 is used when the variable is not related to any object such as Job Control parameters.

Calibration Parameters 

Clicking the Parameters button opens the Calibration Parameters dialog. This table is used to store each calibration parameter with the Object and XP Variable it is derived from, its unique four-character alphanumeric PEST ID, and the parameter’s initial value. The following functions operate on the table.

    • Row. The row number for the calibration parameter that PEST will adjust in the calibration process.
    • Object. The network object that the calibration parameter is associated such. The object column contains the link or node name. Some of the object names are indexed such as 103#2 which represents the second subcatchment of a node in the Runoff Layer.
    • XP Variable. This column contains the XP variable name (XPX field name) for the calibration parameter. 
    • PEST ID. A unique alphanumeric 4 character ID for the calibration parameter.
    • Initial Value. The initial or starting value of the calibration parameter for the calibration process. This value is also the current numerical value of the calibration parameter if the parameter was imported through an XPX file.
    • Calibrated Value. The value of the parameter that has been estimated by a PEST analysis. These values are held in the .REC or record file and are loaded into the table by executing the Load Calibrated Values command. 

Insert/Delete Row

Inserts or deletes a selected row from the observation table.

Parameter File

Edit

Loads the current parameter file into the editor. Initial values of each calibration parameter could be modified in the editor or changed in the calibration parameter table.

Precision

Single/Double. Selecting the radio button on Single or Double instructs PEST to write parameters to model input files using single precision or double precision protocol. For single precision the parameter values will never be greater than 13 characters in length (even if the parameter space allows for a greater length) and the exponentiation character is “e”. For double precision parameter values are written to model input files using double precision protocol; the maximum parameter value length is 23 characters and the exponentiation symbol is “d”. Double precision is suitable for extremely large and extremely small numbers. These controls refer to the PEST “PRECIS” parameter. 

XPSWMM prepares a template files with 10 spaces for PEST to write the parameter values. In some cases more spaces to represent very large or small numbers in double precision may be required. In these cases load the template file into the editor and manually add more spaces.

Point/Nopoint. Selecting the radio button on Point or Nopoint instructs PEST to always use or omit the decimal point in the representation of a number if it can when writing the data file. These controls refer to the PEST “DPOINT” parameter.

If a parameter space is 13 characters wide or greater and the precision is “single”, PEST will include the decimal point regardless of the setting of “DPOINT”, for there are no gains to be made in precision through leaving it out. Similarly, if “PRECIS” is set to “double”, no attempt is made to omit a decimal point if the parameter space is 23 characters wide or more.

The table below shows how the setting of DPOINT affects the representation of the number 12345.67. In examining this table, remember that PEST writes a number in such a way that the maximum possible precision is “squeezed” into each parameter space.

Parameter Space Width
(Characters) 
DPOINT
"point""nopoint"

8

12345.67123545.67
712345.712345.7
612346.12346.
51.2e412346
41.e412e4
3***1e4
2****


Control File

Generate. Generates a default PEST control file using the MAKES CTL function designated in the SWMXP.INI file. This file will include default values for the input parameters of PEST, the calibration parameters in the parameter file, and will reference the instruction file and template file you have created. It will then need to be edited to replace default values and commands with ones appropriate for your modeling.

Edit. Loads the current PEST control file into the current editor. The file must then be modified by replacing default values with appropriate PEST input parameters. 

Check. Reads the PEST Control file, making sure that all necessary items of information are present on this file and that every item is consistent with every other item. It also checks that all parameters and observations cited in the PEST control file are also cited in the template file(s) and instruction file(s) referenced in the PEST control file, and that parameters and observations cited in the template file and instruction file are also listed in the PEST control file.

Create Files

Creates the template file which PEST uses to create an updated data file (.DAT) to send to the SWMM engine by substituting the PEST ID for the numerical value contained in the DAT file. In addition, a parameter file is created to generate the starting values for the first PEST execution of the model and these string values are used in the creation of the PEST control file. After the creation of these files a CALIBRAT.LOG file will be displayed in the current editor listing any errors in the creation of the template file. Such errors may include parameters that are not currently supported in the calibration procedure or objects that cannot be located in the data file.

Important:

Two conditions must be met for the insertion of a calibration parameter into the template file. The first is that the object and SWMM input parameter referenced by the XPX variable must be found in the data file. In other words, no substitution of PEST ID’s will be performed if the object and corresponding variable are not found in the data file. The second condition requires that the XP variable be contained in the calibration library file. This file contains all of the default XP variables that can be used in the automatic calibration option of XP-SWMM.

Instruction File

The following are the available commands for the Instruction File section of the Calibrate Model dialog:  

    • Generate. Generates the first line of an instruction file and places all of the observation variables from the observation table on separate lines.
    • Edit. Loads the current instruction file with all of the observation variables into the editor designated in the SWMXP.INI file. The file must then have relevant search text appropriately entered to locate these variables in the output file(.OUT) and/or other text file(s). 
    • Check. Checks the syntax and searching capabilities of the instruction file with the output file (.OUT). This is accomplished by sending the instruction file name and path along with the output file (.OUT) name and path to the CHK INSTRUCTION function designated in the SWMXP.INI file. A INSCHEK.LOG file is then created and displayed in your current editor displaying all warnings, errors and confirmation messages. 

Load XPX Variables

This button imports an XPX file into the calibration parameter table. The use of an XPX file for the import of calibration parameters is a novel approach. The export of an XPX file is a very powerful function that allows the user to export a selection of variables and objects. For example the user may highlight a particular branch of the network and choose the % impervious of each subcatchment and the pipe roughness used in the EXTRAN layer. This XPX file can then be imported and a PEST ID would be assigned for each of these parameters. A large amount of parameters can be selected and easily imported in this fashion to generate the template that PEST will use. In essence, the XPX file contains all of the parameters you are freeing up so that PEST may adjust them in the calibration process.

Template File

Edit. Loads the current template file into the editor designated in the SWMXP.INI file. The file will be similar to the data file (DAT) but have PEST ID’s inserted throughout the file separated by a delimiter. Subsequent editing or modification of the template file can then be performed within the editor if required.

Check. Checks the syntax of the template file and prepares a data file using the calibration parameter values contained in the parameter file. This is accomplished by sending the template file name and path, the data file (DAT) name and path along with the parameter file name and path to the CHK_TEMPLATE function designated in the SWMXP.INI file. A TEMPCHEK.LOG file is then created and displayed in your current editor displaying all warnings, errors, and confirmation messages.