Latest revision as of 17:46, 22 July 2013

ERDC Automated Model Calibration Software

Research at the U.S. Army Engineer Research and Development Center (ERDC) has focused on the development of methodologies, or improvement of the efficiency of native algorithms, for the computer-based calibration of hydrologic and environmental models (wherein by efficiency we mean the number of forward model calls necessary for the calibration algorithm to converge on a solution). Our software is written to accommodate a popular model independent and input control file protocol. Two ERDC Technical Reports published in early 2012 demonstrate, by way of example(s), how to use the ERDC implementations of (1) the Levenberg-Marquardt (LM) local search method , and also the Secant LM (SLM) method, an efficiency enhancement to the LM method, and (2) the stochastic global optimization method MLSL, which uses our LM/SLM method for local searches, to calibrate, in a model independent manner, a Gridded Surface Subsurface Hydrologic Analysis (GSSHA) hydrologic model. The two noted technical reports, their related appendix material, and all of the files associated with the examples discussed in each respective report are provided below.

Following the initial efforts documented in the two noted technical reports, the LM/SLM and MLSL methods, as well as the stochastic global optimization methods multistart (MS) and trajectory repulsion (TR), which also use the ERDC LM/SLM method implementations for local searches, were directly interfaced with the GSSHA model such that they can be treated as alternate GSSHA run modes. Hence, there are four alternate GSSHA run modes that employ ERDC model calibration software, and their practical use is discussed in the section below titled “Four Alternate GSSHA Run Modes”.

Although the ERDC automated model calibration software was written, as previously mentioned, to accommodate a popular model independent protocol, to be consistent with the other alternate GSSHA run modes (such as, Batch, SCE, Monte Carlo), the GSSHA value replacement functionality was utilized instead when the ERDC automated model calibration software was directly interfaced with the GSSHA model to develop the four alternate GSSHA run modes. For clarity, it should be emphasized that one has the flexibility to calibrate a GSSHA hydrologic model either in a model independent manner, as specified in the two noted technical reports, or by using one of the four alternate GSSHA run modes.

We recommend that one calibrate a GSSHA hydrologic model using one of the four alternate GSSHA run modes given that the other alternate GSSHA run modes (such as, Batch, SCE, Monte Carlo) also use the GSSHA value replacement functionality. The two previously mentioned technical reports which describe in a clear and practical way how to calibrate, in a model independent manner, a GSSHA hydrologic model are provided, not only for completeness, but also because the documentation is a primary basis to prepare to use any one of the four alternate GSSHA run modes that employ ERDC automated model calibration software.

The section below titled “Four Alternate GSSHA Run Modes” describes the/an initial approach that one can take to utilize any one of the four alternate GSSHA run modes, and content within the individual sections (i.e., 18.6.1 – 18.6.4) contains any additional run mode specific information that must be supplied to support the use of that given alternate run mode to calibrate a GSSHA hydrologic model. Please note that later this calendar year (2012), a published ERDC Technical Note, similar to the two previously mentioned and provided ERDC TRs that document in a clear and practical way how to use the independent ERDC LM/SLM and MLSL implementations to calibrate a GSSHA hydrologic model in a model independent manner, will be provided at this location and its contents will briefly describe and also document, in a clear and practical way, how to use the four alternate GSSHA run modes for practice driven application.

Available project resources more often than not limit the time that one can devote to model calibration, and if so, then we recommend that one use the SLM method, possibly also with prior information (please see example 11 in the technical report ERDC-CHL-TR-12-3, below, for an example problem that could serve as a go by). However, if resources do permit a more thorough exploration of model parameter space, then, of the three available stochastic global optimization methods; viz., MS, TR, and MLSL, we recommend that one use MLSL.

For further assistance with using the independent ERDC LM, SLM, and MLSL implementations to calibrate a GSSHA hydrologic model in a model independent manner, or with using any one of the four alternate GSSHA run modes, please contact Brian Skahill at Brian.E.Skahill@usace.army.mil or 503-808-3973, or the principal GSSHA hydrologic model developer Charles W. Downer at charles.w.downer@usace.army.mil.

Model Independent Calibration

A Practical Guide to Calibration of a GSSHA Hydrologic Model Using ERDC Automated Model Calibration Software - Efficient Local Search

ERDC-CHL-TR-12-3 A Practical Guide to Calibration of a GSSHA Hydrologic Model Using ERDC Automated Model Calibration Software - Efficient Local Search

ERDC-CHL-TR-12-3 Appendix Material

Example problems for ERDC-CHL-TR-12-3

A Practical Guide to Calibration of a GSSHA Hydrologic Model Using ERDC Automated Model Calibration Software - Effective and Efficient Stochastic Global Optimization

ERDC-CHL-TR-12-2 A Practical Guide to Calibration of a GSSHA Hydrologic Model Using ERDC Automated Model Calibration Software - Effective and Efficient Stochastic Global Optimization

ERDC-CHL-TR-12-2 Appendix Material

Example problems for ERDC-CHL-TR-12-2

Four Alternate GSSHA Run Modes

The four alternate GSSHA run modes are (1) Efficient Local Search, (2) Multistart, (3) Trajectory Repulsion, and (4) Effective and Efficient Stochastic Global Optimization, and as previously mentioned, their practical use is discussed here and also in sections 18.6.1 - 18.6.4, respectively. The "Efficient Local Search" and "Effective and Efficient Stochastic Global Optimization" GSSHA run modes refer to the SLM and MLSL methods, respectively. As was previously mentioned, to be consistent with the other alternate GSSHA run modes (such as, Batch, SCE, Monte Carlo), the value replacement functionality is utilized for each of the four alternate GSSHA run modes that employ ERDC automated model calibration software (please see section 18.2 Simulation Setup for Alternate Run Modes for guidance regarding the GSSHA value replacement functionality). It is emphasized that it is assumed that the list of parameter names and their associated values that are provided within the GSSHA value replacement files designated by REPLACE_PARAMS and REPLACE_VALS, that must be specified in the GSSHA project file, are in the same order as they are also specified in the control file that will likely be prepared beforehand, as will be presented below.

Before describing the general path forward to using any one of the four alternate GSSHA run modes that employ the ERDC automated model calibration software, please also note that in the control file that must be prepared to guide the automated model calibration process using any one of the four GSSHA run modes, one still has the flexibility to designate parameters as log transformed, none, fixed, or tied (please see the ERDC-CHL-TR-12-3 technical report for further discussion, in particular, examples 8 and 9 in the report).

To employ any one of the four alternate GSSHA run modes to calibrate a given GSSHA hydrologic model deployment, we strongly recommend that one first follow the steps listed in example 1 in the technical report ERDC-CHL-TR-12-3, provided above, which will result in preparation of all of the files that are necessary to calibrate the GSSHA hydrologic model in a model independent manner using ERDC software.

Of course, when the time comes during this process to specify adjustable GSSHA model parameters (viz., step 2 in example 1 in ERDC-CHL-TR-12-3), it is presumed that one has some sense as to what GSSHA model parameters one wants to designate as adjustable for the specific GSSHA application under consideration. Please do not blindly mimic what is provided in example 1 in ERDC-CHL-TR-12-3. The example depicts the general sequence of steps required to employ automated model calibration software. It does not serve as general guidance for which GSSHA model parameters to specify as adjustable when calibrating a GSSHA hydrological model. In general, what hydrologic model parameters to specify as adjustable is a function of the complexity that one has expressed in the model, the predictions of interest for the deployed model, and their sensitivities to that specified model complexity.

Upon completing the necessary steps to calibrate the GSSHA hydrologic model in a model independent manner using ERDC software, as outlined in example 1 in the technical report ERDC-CHL-TR-12-3, provided above, there are a few modifications to the prepared files, in addition to the preparation of an additional input file, that are required to subsequently enable use of any one the four alternate GSSHA run modes. Directly below, we briefly discuss the relatively minor changes that are required regardless of which alternate GSSHA run mode is utilized. Each individual section (viz., 18.6.1 – 18.6.4) includes any additional GSSHA run mode specific information that must be prepared, the syntax for using that specific run mode, and also an example problem that one can follow. Upon completing the necessary steps to calibrate the GSSHA hydrologic model in a model independent manner using ERDC software, the relatively minor changes that are required regardless of which alternate GSSHA run mode is utilized include the following:

1. Include on a new line at the end of the control data section of the prepared control file the name of the GSSHA project file (for further clarity, if needed, then please inspect the control data section of the control file in the example provided in any one of the individual sections (viz., 18.6.1 – 18.6.4) and compare it with the contents of appendix 10 that list the contents of the control file upon completion of step 7 in example 1 presented in the technical report ERDC-CHL-TR-12-3).
2. The model command line section of the prepared control file will include one line with the entry “model.bat” following the steps listed in example 1 in the technical report ERDC-CHL-TR-12-3, provided above. Replace the one line model command line section entry “model.bat” with two lines, the first line containing “preGSSHA.bat”, and the second line containing “postGSSHA.bat”. It should be noted that the existence and contents of a file named “preGSSHA.bat” is currently of no consequence. It was used temporarily during source code development, but later discarded with for the current implementation(s) for each of the four alternate GSSHA run modes. What is of importance; however, is the file named “postGSSHA.bat”, and its contents are a subset of those already contained in the previously prepared batch file named “model.bat”. In particular, the contents for the file named “postGSSHA.bat” effectively include, as its name suggests, the contents from the previously prepared batch file named “model.bat” which follow the actual forward model (i.e., GSSHA call) execution call.
3. The next step is to prepare the two files that were referred to above; viz., the GSSHA value replacement files designated by REPLACE_PARAMS and REPLACE_VALS that must be specified in the GSSHA project file to support use of the GSSHA alternate run modes. The preparation of these two files is relatively straightforward upon completing the steps necessary to calibrate the GSSHA hydrologic model in a model independent manner using ERDC model calibration software. To prepare the REPLACE_PARAMS file designated in the GSSHA project file, simply copy the parameter names as they are listed in the parameter data section of the control file into a new file, after specifying on the first line of this new file the number of parameters, which is already known, and its value is specified at the first entry, an integer value, on the fourth line of the control file (or second line of the control data section of the control file). Afterwards, place a ‘[‘ character before the name of each parameter and a ‘]’ character at the end of the name of each parameter, with no space between the noted characters and the begin and end of each parameter name. At this point, each line of the REPLACE_PARAMS file following the first line, which indicates the number of parameters, is of the form [parameter_name_i], for i = 1, …, n, where n is the number of parameters. Modify each one of the lines following the first to be of the form [parameter_name_i] “%lf”, to designate that each of the parameters will be treated as a double during model calibration. The REPLACE_VALS file is quickly and easily prepared – simply copy the initial values specified for each parameter as listed in the fourth column of the parameter data section of the control file into a new file and place the parameter values on a single line with one or more spaces between each specified parameter value. Assistance with preparing these two files can also be found, as previously mentioned, in section 18.2 Simulation Setup for Alternate Run Modes. Moreover, the respective REPLACE_PARAMS and REPLACE_VALS files are also provided in any one of the example problems provided in each section (i.e., 18.6.1 – 18.6.4).
4. If the steps in example 1 in the technical report ERDC-CHL-TR-12-3 were followed as recommended, then there now exists one or more model input template files that were prepared to support model independent model calibration using ERDC software. Make a copy of each of the current one or more model input template files, and ensure that the name of each file copy is the appropriate model input file specified in the GSSHA project file. For example, if the model input template file for the GSSHA MAPPING_TABLE file is currently named input.cmt.tpl, and it is the basis for generating the actual GSSHA MAPPING_TABLE file specified in the GSSHA project file, named gssha_input.cmt, then rename the file copy of the template file named input.cmt.tpl to gssha_input.cmt. For each of the appropriately renamed template file copies, subsequently (1) delete the first line that starts with “ptf”, and (2) replace the existing template file specified adjustable model parameter designator; for example, ‘$’ upon inspection of the template files listed in appendices 1 and 2 associated with the technical report ERDC-CHL-TR-12-3, with that which is used for the GSSHA value replacement functionality; viz. ‘[’ and ‘]’ placed at the very beginning and end of the specified adjustable model parameter name (i.e., ensure that there are no spaces between ‘[’ and ‘]’ and the beginning and ending of the name of the specified adjustable model parameter).

As previously indicated, each individual section (18.6.1 – 18.6.4) includes (1) any additional run mode specific information that must be prepared to support use of that specific alternate GSSHA run mode, (2) the syntax for the given alternate GSSHA run mode, and (3) also a test problem which one can use as a go by. Please further note, as previously mentioned, that later this calendar year (2012), a published ERDC Technical Note, similar to the two previously mentioned and provided ERDC TRs that document in a clear and practical way how to use the independent ERDC LM/SLM and MLSL implementations to calibrate a GSSHA hydrologic model in a model independent manner, will be provided at this location and its contents will briefly describe and also document, in a clear and practical way, how to use the four alternate GSSHA run modes for practice driven application.

GSSHA Executables with the Four Alternate GSSHA Run Modes

GSSHA 5.7a Windows 32-bit, Debug Mode. With the Four New ERDC Alternate Run Modes. Date: April 10, 2012

GSSHA 5.7a Windows 32-bit, Release Mode. With the Four New ERDC Alternate Run Modes. Date: April 10, 2012

GSSHA User's Manual

18 Alternate Run Modes

18.1     MPI and OpenMP Parallelization

18.2     Simulation Setup for Alternate Run Modes

18.3     Batch Mode Runs

18.4     Automated Calibration with Shuffled Complex Evolution

18.5     Monte Carlo Runs

18.6     ERDC Automated Model Calibration Software

   18.6.1     Efficient Local Search

   18.6.2     Multistart

   18.6.3     Trajectory Repulsion

   18.6.4     Effective and Efficient Stochastic Global Optimization

18.7     Inset Models