Calibrating Watroute and Standalone
MESH with Ostrich: Sample Files
For Microsoft Windows
Ostrich is a calibration utility that can be used to calibrate the parameters of Standalone MESH and of
Watroute. Standalone MESH can be calibrated separately or as a coupled model with Watroute.
Other documents describe compiling, configuring, and running both Standalone MESH and Watroute.
Similar documents exist for configuring Ostrich, including the Ostrich Manual.
Certain features of Ostrich have not yet been documented, and are briefly described, along with two
sample calibration setups, in this document. The first sample is a simple calibration of Standalone MESH;
the second is a simple calibration of Standalone MESH coupled with Watroute. There is no sample
calibration setup for Watroute, as a standalone model, as it requires runoff and recharge input files, which
are generated by Standalone MESH.
Software Requirements
While Watroute, ‘redist_new_ch_par’, ‘Watroute_SimStat’, and Standalone MESH can be compiled from
code on the repository, Ostrich and its accompanying utilities must be downloaded as pre-compiled
binaries from the MESH Wiki. Instructions for acquiring the necessary binaries are not provided in this
document. This document only provides an overview of two sample calibration setups.
Calibrating Standalone MESH with Ostrich
Calibrating Standalone MESH requires an existing setup of the model. The setup should include forcing
data and input files, and should run with an existing set of parameter files. Ostrich can then be used to
perform a calibration to fine-tune the values in the parameter files.
The sample setup of a simple calibration of Standalone MESH can be downloaded from the MESH Wiki
or FTP site and then extracted.
File Structure
The sample setup contains a number of folders and files.

MESH will not create the output folder, so it should exist prior to running the model. The name of
the folder is specified in “MESH_input_run_options.ini” (e.g., “BASINAVG1”).
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
1 of 24

All of the files required to run Ostrich as contained in the “ost” folder.

Likewise, the “ost” folder contains other sub-folders and files.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
2 of 24

The “best” folder will contain the output and parameter files corresponding to the parameter set
that best satisfies the objective function of the calibration.
o The name of the folder is specified in “save_best.bat”.

The “OUTPUT” folder will contain output from Ostrich.
o The name of the folder is specified in “Ostrich.bat”.
Configuring Ostrich
While the Ostrich folder contains a number of files, the actual configuration of Ostrich for the calibration
is set in the “OstIn.txt” file.

This document provides a brief overview of “OstIn.txt” for configuring Ostrich. Consult the
Ostrich Manual for more information.
Program Type
The program type is the type of calibration to be performed by Ostrich. More specifically, the value of the
“ProgramType” attribute should correspond to one of the supported calibration algorithms. The “DDS”
algorithm is normally used to calibrate Standalone MESH. Alternatively, “ModelEvaluation” can be
used to test the configuration of the model (e.g., in a ‘run-once’ fashion).


Lines that begin with the ‘pound’ symbol (e.g., “#”) are ignored by Ostrich.
Attributes are separated from values, and values from other values, by whitespace (e.g., a space).
Template Files and Parameters
Template files are explained in the Ostrich manual. A template file is a copy of the parameter file being
modified by Ostrich, except that it contains ‘tokens’ in place of certain parameter values.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
3 of 24

A token is replaced with a permutation of the parameter value during calibration.

Template files are defined in the “FilePairs” block of the Ostrich configuration file,
“OstIn.txt”.

Tokens are listed in the “Params” block. The lower and upper bounds and format of the
corresponding parameter value are specified.
o
The name of the token should be the same character length as specified in the format
statement (e.g., 6 characters long if the format is “F6.3”).
Algorithm Characteristics
Characteristics of the algorithm are specified within a block, whose ‘begin’ and ‘end’ tags correspond to
the name of the algorithm specified as the “ProgramType”.
Different algorithms contain different attributes.


For DDS, the perturbation value, “PerturbationValue”, is specified (e.g., “0.2”).
The maximum number of iterations, “MaxIterations”, must also be specified.
o
𝑁
𝜆
This value can be calculated as 𝑖 = , where 𝑁 is the total number of parameters being
calibrated and 𝜆 is the perturbation value (e.g., 𝜆 = 0.2).
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
4 of 24

The “UseInitialParamValues” keyword signifies that user-defined values specified in the
“InitParams” block are to be used to initialize the parameter values.
o
The parameters should be listed horizontally in the “InitParams” block, in the same
order as they are listed vertically in the “Params” block.
Objective Function
The objective function is specified at the beginning of the file.

The “GCOP” objective function allows the Nash-Sutcliffe coefficient that is calculated by
Standalone MESH (e.g., “NS.txt”) to be used as the objective function.
o The Nash-Sutcliffe coefficient is traditionally used in assessing the fit of a simulated
hydrograph to measured streamflow data.

The “PreserveBestModel” attribute allows a batch file to be called to save the current state of
the model when the value of the objective function has improved.

Characteristics of “GCOP” are specified in the “GCOP” block.
o “CostFunction” corresponds to a tied response variable in the file (discussed later).
o The additive “PenaltyFunction” (e.g., “APM”) is used.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
5 of 24
The tied response variable (e.g., “NegNS”) is necessary to transform the objective function.

Calibration in Ostrich works by minimizing the objective function. However, the objective of
calibrating to a Nash-Sutcliffe value is to maximize the objective function. To transform the
Nash-Sutcliffe value, the value calculated by MESH (e.g., “NS.txt”) is multiplied by a weight of
“-1.0”.

The actual Nash-Sutcliffe coefficient is read from a file in the Ostrich folder, named
“FunctionOut.txt”.
‘OST-MESH’ batch file
Batch files have been created to automate the process of calibrating Standalone MESH. “OST-MESH.bat”
is called by Ostrich in lieu of calling the raw executable of the model.

The purpose of calling the batch file is to allow for additional file handling before and after
running the model.
The file contains a number of commands.

The batch file first navigates to the MESH folder.

The name of the MESH executable is set at ‘Line 8’.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
6 of 24

The name of the output file containing the result of the objective function calculated by MESH,
or ‘outfile’ is set at ‘Line 11’.

A ‘bad’ value is set at ‘Line 14’. Ostrich requires the ‘outfile’ to exist, regardless of the success of
running MESH. If the batch file is able to recognize a bad run of MESH, the ‘bad’ value is
assigned to the ‘outfile’, such that Ostrich will recognize a poor calibration result.
Calibration Iteration

The first thing that the batch file does is delete an existing ‘outfile’.

The batch file then copies the parameter files created by Ostrich to the MESH folder, and runs
MESH.

If MESH does not create an ‘outfile’ after the run (e.g., a failed run), the batch file copies the
‘bad’ value to the ‘outfile’ and then copies the ‘outfile’ to the Ostrich folder.

Finally, the batch file navigates back to the Ostrich folder.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
7 of 24
‘Save Best’
When a particular set of parameter values improves the objective function, the output from the model and
corresponding parameter files are preserved. This functionality is configured with the
“PreserveBestModel” attribute in “OstIn.txt”.

The “save_best.bat” batch file creates the “best” folder in the Ostrich folder, if one does not
exist. The name of the folder is specified in ‘Line 5’.

The batch file then copies the parameter files, log file, and streamflow file from the MESH folder
to the “best” folder.

Other files can be added to this list, as required.
o The format of the command is “copy ..\fromFile best\toFile”. Ostrich calls
“save_best.bat” from the Ostrich folder, so a relative path is included to point back to
the MESH folder; the “best” folder exists in the Ostrich folder.
Testing the Configuration
The “ModelEvaluation” ‘algorithm’ is a good way to test the configuration of Ostrich. If the model runs,
then Ostrich is able to configure the parameter files of the model.



Navigate to the “ost” folder.
Open “OstIn.txt”.
Set the “ProgramType” to “ModelEvaluation”.

Save the file.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
8 of 24

Run “Ostrich.bat”.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
9 of 24
o
The ‘Ostrich Monitoring’ utility will open.
Running Ostrich
To run Ostrich, and perform a calibration of Standalone MESH, run “Ostrich.bat”.




First, revert the “ProgramType” to “DDS”.
Navigate to the “ost” folder.
Open “OstIn.txt”.
Set “ProgramType” to “DDS”.

Save the file.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
10 of 24

Run “Ostrich.bat”.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
11 of 24
o

The ‘Ostrich Monitoring’ utility will open.
 A summary of the evaluations will be listed in the “Summary of all model
runs” window.
 Model output (e.g., what would normally be seen when running the model) will
display in the “Output of current model run” window.
To stop Ostrich, click “Stop Ostrich”.
o Ostrich will stop at the end of the current iteration.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
12 of 24
Output

Navigate to the “OUTPUT” folder.
o Details of the calibration are listed in “OstOutput0.txt”.


Navigate back to the Ostrich folder.
Navigate to the “best” folder.
o The folder contains the output and parameter files corresponding to the optimal parameter
set.
Calibrating Standalone MESH with Watroute
The process of calibrating Standalone MESH with Watroute is largely the same as calibrating Standalone
MESH.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
13 of 24
File Structure

A “watroute” folder is added to the MESH folder.

The “watroute” folder contains most of the files required to run Watroute.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
14 of 24

The event file (e.g., “event.evt”) is modified to use the drainage database file, runoff, and
recharge files from the MESH folder.
Configuring Ostrich

A template file for the ‘import channel parameter’ file is added to the “ost” folder.

Likewise, the template file is added to the “FilePairs” block in “OstIn.txt”.

The “ModelExecutable” and “PreserveBestModel” attributes are updated in “OstIn.txt”.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
15 of 24

Additional parameters are added to the “Params” block for Watroute.
Compiling and Configuring ‘redist_new_ch_par.exe’
‘redist_new_ch_par.exe’ is a utility to distribute channel parameter values from the ‘import channel
parameter file’ (e.g., “import_new_ch_par.txt”) to the grid format used by Watroute.

Instructions for compiling and configuring ‘redist_new_ch_par.exe’ are provided in the document
titled ‘Compiling and Configuring Watroute’ in the ‘Channel parameter file (‘new_ch_par.r2c’)’
section.
To simplify the file structure when coupling Standalone MESH with Watroute, ‘redist_new_ch_par.exe’
and its input files should reside in the “watroute” folder.

“import_new_ch_par.txt” is written by Ostrich.
Compiling ‘Watroute_SimStat.exe’
‘Watroute_SimStat.exe’ is a utility to calculate the Nash-Sutcliffe coefficient from the “spl_rpn.csv”
streamflow output file from Watroute.
Creating the project
Review the documents, ‘Installing Photran and Eclipse’ and ‘Tips for Using Eclipse’, for more
information on installing, configuring, and using Eclipse.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
16 of 24




Open Eclipse.
Open the Fortran perspective.
Create a new project.
o Click “File” in the window menu.
o Click “New”.
o Click “Fortran Project”. A new window will open.
o Name the project “Watroute_SimStat”.
o Select “Executable (Gnu Fortran on Windows)” as the “Project type”.
o Click “Finish” to close the window and create the project.
Configure the ‘build’ properties of the project.
o Right-click on the project in the “Project Explorer” pane.
o Click “Properties” from the context menu.
o Select “Fortran Build” from the side-pane menu.
o For MinGW (not required for Cygwin):
 Uncheck “Use default build command”.
 Change the “Build Command” from “make” to “mingw32-make”.
o Uncheck “Generate Makefiles automatically” in the “Makefile generation”
group.
o Update the “Build directory” to be the project location (e.g.,
“${workspace_loc:/Watroute_SimStat}”).
o Click “OK” to close the window.
Adding source code
 Link to the ‘Watroute_SimStat’ source code.
o Right-click on the ‘Watroute_SimStat’ project in the “Project Explorer” pane.
o Click “Import…” from the context menu. A new window will open.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
17 of 24
o
o
o
Expand the “General” item.
Select “File System”.
Click “Next”.
Browse to the ‘Watroute_SimStat’ source code folder (e.g.,
“TRUNK\Post_Process\Watroute_SimStat”).
o Select the program file: “Watroute_SimStat.f90”.
o Click “Advanced > >”.
o Check “Create links in workspace”.
o Check “Create virtual folders” if it is unchecked.
o Click “Finish”.
Link to the ‘watroute’ source code.
o Right-click on the ‘Watroute_SimStat’ project in the “Project Explorer” pane.
o Click “Import…” from the context menu. A new window will open.
o

Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
18 of 24
o
o
o
Expand the “General” item.
Select “File System”.
Click “Next”.
Browse to the ‘watroute’ source code folder (e.g.,
“TRUNK\Routing_Model\RPN_watroute\code”).
o Select the following files: “area_watflood.f”, “EF_Module.f”,
“EF_ParseUtilities.f”, “rdevt.f”, and “read_flow_ef.f”.
o Click “Advanced > >”.
o Check “Create links in workspace”.
o Check “Create virtual folders” if it is unchecked.
o Click “Finish”.
Link to the ‘MESH driver’ source code.
o Right-click on the ‘Watroute_SimStat’ project in the “Project Explorer” pane.
o Click “Import…” from the context menu. A new window will open.
o

Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
19 of 24
o
o
o

Expand the “General” item.
Select “File System”.
Click “Next”.
o Browse to the ‘MESH driver’ source code folder (e.g., “TRUNK\Driver\MESH_Driver”).
o Select the following files: “Julian_Day_ID.f”, “NSE.F90”, “SAE.F90”, “SAEMSRT.F90”,
“SAESRT.F90”, “SIMSTATS.F90”, “SORT.F90”, and “TEST_CSV.F90”.
o Click “Advanced > >”.
o Check “Create links in workspace”.
o Check “Create virtual folders” if it is unchecked.
o Click “Finish”.
Import the ‘Watroute_SimStat’ makefile.
o Right-click on the ‘Watroute_SimStat’ project in the “Project Explorer” pane.
o Click “Import…” from the context menu. A new window will open.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
20 of 24
o
o
o
Expand the “General” item.
Select “File System”.
Click “Next”.
Browse to the ‘Watroute_SimStat’ source code folder (e.g., “TRUNK\Post_Process\
Watroute_SimStat”).
o Select two files: “makefile” and “makefile.def”.
o Click “Finish”.
 It is best practice to import a copy of the makefile than to create a link to the file
on the repository. The makefile contains local machine information, such as the
local path to a copy of the repository. This type of local and machine-specific
information should not be committed to the repository.
o
Updating the path to the repository in the Makefile
 Update the path to the local repository.
o Open “makefile.def”.
 If the file does not open in the local editor, right-click on the file. Click “Open
With” from the context menu, and then click “Other…”. A new window will
open. Select “Makefile Editor”. Click “OK” to close the window.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
21 of 24
Change the “DIR_REPO” variable from the default directory (e.g., “C:\SA_MESH\TRUNK”)
to the path of either the ‘Trunk’ or a ‘Tag’ folder on the local repository.
o Save the file.
o
Compiling the project
 Right-click on the project in the “Project Explorer” pane.
 Click “Build Project” from the context menu.
o Compiling the project might take some time.
o Once the project has successfully compiled, the “Console” pane will show the
“Watroute_SimStat is now up to date…” message.
 “Watroute_SimStat.exe” should be listed as a child of the “Binaries” item of the project in the
“Project Explorer” pane.
 Copy “Watroute_SimStat.exe” to the “watroute” folder.
‘OST-MESH_Watroute’ Batch File
The process of running Ostrich remains the same; however, different batch files are used.

The ‘OST-MESH_Watroute’ batch file first calls the ‘OST-MESH’ batch file to run MESH.

Because the last step in the ‘OST-MESH’ batch file is to return back to the “ost” folder, the next
command in ‘OST-MESH_Watroute’ is to return to the MESH folder.

The filenames of ‘redist_new_ch_par.exe’, Watroute, and ‘Watroute_SimStat’ are set in ‘Lines
15-17’.

As with ‘OST-MESH’, a ‘bad’ value is set in ‘Line 20’.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
22 of 24

The name of the original ‘flowinit’ file is set in ‘Line 23’.

The name of the ‘outfile’ containing the objective function calculated by ‘Watroute_SimStat’ is
set at ‘Line 26’.


The ‘import channel parameter’ file created by Ostrich is copied to the “watroute” folder.
The batch file then opens the “watroute” folder and deletes an existing ‘outfile’.

‘redist_new_ch_par.exe’ is run to create the grid (e.g., “*.r2c”) channel parameter file, required
by Watroute.

The original ‘flowinit’ file is copied and named “flow_init.r2c” for Watroute, and an existing
comma-separated (e.g., “*.csv”) file is deleted, before ultimately running Watroute with the
“streamflow_comparison” argument.

‘Watroute_SimStat’ is run to calculate the objective function.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
23 of 24

The ‘outfile’ is copied to the “ost” folder.
o If the run failed and the ‘outfile’ does not exist, one is created using the ‘bad’ value.

Finally, the batch file returns to the “ost” folder.
‘Save Best’
The ‘save_best’ batch file for Standalone MESH with Watroute is similar to the file for Standalone
MESH.

The batch file calls ‘save_best’ for Standalone MESH to preserve the output and parameter files
from the MESH folder.

The batch file then preserves certain output and input files from the “watroute” folder.

Other files can be added to this list, as required.
o The format of the command is “copy ..\fromFile best\toFile”. Ostrich calls
“save_best.bat” from the Ostrich folder, so a relative path is included to point back to
the MESH folder; the “best” folder exists in the Ostrich folder.
Calibrating Watroute and Standalone MESH with Ostrich: Sample Files-February 18, 2016
24 of 24