Getting Started with Canada's Hydrology
Land Surface Scheme Simulator (MESH)
Paul Smith, Muluneh Mekonnen, Ali Nazemi, Bruce Davison
Summer 2013
2
MESH Preparation Tutorial
Table of Contents
1. Introduction ...............................................................................................................................................................4
2. MESH Drainage Database File Preparation Procedure ..............................................................................................5
2.1 Obtain required files ...........................................................................................................................................5
2.2 Modifying the DEM file using ArcGIS ..................................................................................................................5
2.3 Select Ecodistrict data with ArcGIS ...................................................................................................................12
2.4 Create the Watershed in GreenKenue ..............................................................................................................15
2.5 Complete Watflood map ...................................................................................................................................20
2.6 Modify the .map file and execute BSN.exe .......................................................................................................25
3. MESH Land Cover Determination and CLASS File Preparation ................................................................................29
3.1 Modify the Land Cover Files Using ArcGIS ........................................................................................................29
3.2 Extracting the Land Cover Data .........................................................................................................................33
3.3 Determine the Land Cover Percentages in Excel ...............................................................................................36
3.4 Adjust the CLASS Input Files ..............................................................................................................................39
4 Production of Remaining MESH Files........................................................................................................................42
4.1 Required Data and Executables ........................................................................................................................42
4.2 Pre-run organization .........................................................................................................................................42
4.3 Minor file construction ......................................................................................................................................46
4.4 MESH input run options ....................................................................................................................................48
4.5 MESH hydrology parameters ............................................................................................................................49
4.6 .BAT file Modification ........................................................................................................................................49
4.7 MESH test run ...................................................................................................................................................50
5. Preparation of Ostrich and its files ..........................................................................................................................53
5.1 Ostrich preparation ...........................................................................................................................................53
5.2 Final test run .....................................................................................................................................................58
6. Common Errors ........................................................................................................................................................60
6.1 Coordinate Issues ..............................................................................................................................................60
6.2 bsn.exe Crashes .................................................................................................................................................62
6.3 run_mesh.bat Errors .........................................................................................................................................63
6.4 Ostrich Quits Prematurely .................................................................................................................................64
7. Acknowledgements ................................................................................................................................................66
8. References and Further Reading .............................................................................................................................67
3
1. Introduction
MESH is the hydrology land-surface modelling extension of Modélisation Environmentale
Communautaire (MEC), developed by Environment Canada (Pietroniro et al., 2007). This model grew
out of the Mackenzie GEWEX study (MAGS), where an attempt was made to create a link between Land
Surface Scheme models (LSS) and hydrological stream flow models. This created the first generation of
combined LSS and stream flow, MESH. Over the years, MESH (also known as MAGS HALL)has been
updated many times with constant revisions being made to improve the system either in performance,
ease-of-use, or scope. Currently, the MESH modelling system can be forced with previously generated
global/regional climate model outputs, gridded observation data or other reanalysis products to address
water security challenges such as the potential impacts of natural variability, along with climate and land
use change on the future of water resource availability.
The goal of this tutorial is to provide a "quick start" document for MESH beginners. This
document assumes no prior knowledge of climate modelling systems and the steps shown here only
require that one have access to MESH (https://wiki.usask.ca/display/MESH/MECMESH+for+standalone+MESH+users+and+developers), Ostrich (http://www.civil.uwaterloo.ca/
lsmatott/Ostrich/OstrichMain.html), and related boundary shape files for the region to be studied.
Other necessary files are available from easily accessible public databases or are created during the
course of the tutorial. If one seeks more in depth information about MESH, CLASS, Ostrich, or the data
sets used, this can be found in the respective user manuals (Davison et al (2009) Verseghy (2008), and
Matott, respectively).
4
2. MESH Drainage Database File Preparation Procedure
The drainage database is the core file for running MESH, describing the stream flow networks,
ecodistrict distribution, elevation, etc. This file is constructed in three distinct stages, the first of which
consists of using ArcGIS modify digital elevation maps (DEM) and ecodistrict boundary shape files to a
state where they can be used as input for GreenKenue. The second stage consists of using GreenKenue
to construct a hydrological map (in the form of .map file) over the basin of interest. The final step takes
this .map file and runs it through bsn.exe (a program created by the MESH team) in order to arrive at the
finalized drainage database file.
2.1 Obtain required files
In order to create the drainage database file, there are four needed files:
- Digital elevation data (DEM)
- Land cover data
- The boundary shape file for the watershed of interest
- Ecodistrict shape file data
For Canada, both the DEM and land cover data can be obtained via Geobase's data tab
(http://www.geobase.ca/). Registration to Geobase is required to obtain files from its archive.
Note: Data is available at the 1:50,000 resolution, but this should be passed over for the
1:250,000 data sets.
The ecodistrict shape file is available from the Agriculture and Agri-Food Canada website:
http://sis.agr.gc.ca/cansis/nsdb/ecostrat/gis_data.html.
The shape file for the area of interest is, in general, not publically available and need to be
obtained from DEM information on a case-by-case basis.
2.2 Modifying the DEM file using ArcGIS
For the purposes of demonstration, here we show the process of drainage database file creation
for the Castle River headwater of the Oldman river using ArcMap 10.1 and GreenKenue
(http://www.nrc-cnrc.gc.ca/eng/solutions/advisory/green_kenue_index.html).
2.2.1) Once all files have been acquired, the first step is to modify (clip) the digital elevation file
to a form that will allow Green Kenue to generate the stream network. To begin, start up ArcMap and
add both your DEM and boundary shape file via the "Add data" button:
5
Frame 2.2.1.1
Note: If a warning pops up that mentions a "lack of pyramids" and offers to create pyramids,
simply click "yes". Furthermore, the "Geographic Coordinate System Warning" can be ignored by clicking
the "close" button.
Figure 2.1: The workspace once both files have been added.
2.2.2) With both files in place, the actual manipulation can begin. Select the "Customize" >
"Toolbars" > "Draw" menu.
6
Frame 2.2.2.1
Select the "Polygon" tool:
Frame 2.2.2.2
Clip an outline around your boundary shape file.
7
Frame 2.2.2.3
Note: Double click to end your polygon construction
Frame 2.2.2.4
The graphic must now be converted to a feature:
8
Frame 2.2.2.5
Within the "Convert Graphics to Features" window, select "this layer's data source" and select
the directory that you want the clip to be saved under (as shown in frame 2.2.2.6).
Frame 2.2.2.6
9
Click "yes" to the box that asks: "Do you want to add the exported data to the map as a layer?"
ArcGIS will then create a third layer in your workspace - once this has been completed, delete the shape
you drew.
Frame 2.2.2.7
2.2.3) Exit the draw tool bar, then open the search bar (Ctrl+f or you can select it from the
menu) and search for "clip Raster". The top result is the one we're interested in.
Frame 2.2.3.1
10
Once in the "clip raster" tool, select your DEM as the input raster, the clip as the output extent,
check the "Use the input features for clipping geometry", and define the folder path and file name for
the output.
Frame 2.2.3.2
After this step, another layer will appear in the layer sidebar with the name assigned to it. As the
last step, the Raster clip must be converted to ASCII fromat. Select "ArcToolbox" > "Conversion Tools" >
"From Raster" > "Raster to ASCII". Select the Raster clip as the input Raster and define the output file
path and file name, ending with a .asc extension.
11
2.3 Select Ecodistrict data with ArcGIS
The next step in preparing the drainage database file is the creation of individual ecodistrict
shape files for all ecodistricts that are covered by the watershed being examined.
2.3.1) Load up the boundary shape file for your watershed as well as the ecodistrict map data. In
order to make the selection of the correct ecodistricts easier, use the "symbol selector" to set the fill to
"hollow". (Note: To get to the symbol selector for a given layer, simply click on the little coloured block
below the layer's name in the "Table of Contents".)
Frame 2.3.1.1
We aim to know exactly which ecodistricts cover our chosen watershed. In order to do this, we
select the properties of our ecodistrict layer.
12
Frame 2.3.1.2
Within the properties menu, select the "labels" tab, check "label features in this layer", set the
label field as "ECODISTRIC", then hit ok.
Figure 2.2: Map with ecodistricts labeled
2.3.2) Use the "select features" tool to individually select each ecodistrict covered by the
watershed.
Frame 2.3.2.1
Once a region has been selected, go the menu: "ecodistricts" > "data" > "export data".
13
Frame 2.3.2.2
Leave the option "this layer's source data" selected and choose a location to save the new shape
file.
Frame 2.3.2.3
Finally, hit "yes" when the "do you want to add the exported data as a layer?" box pops up.
Repeat with all other ecodistricts that happen to cover some of your watershed.
14
2.4 Create the Watershed in GreenKenue
With the groundwork in place, we can now progress to the construction of the .map file through
GreenKenue.
2.4.1) Start GreenKenue and import your clipped file (ASCII data format) along with the shape
file containing the boundary outline of your watershed.
Frame 2.4.1.1
Frame 2.4.1.2
Every piece of data you import will need to be scaled correctly by selecting a uniform spatial
calibration for each layer. In order to do this, right click on any given layer, select properties (as shown in
15
frame 2.4.1.2), and then click the spatial tab. Within the spatial tab, click assign and select the
coordinate system that fits appropriately with the data being used (LatLong with an ellipsoid of
GRS80/NAD83 is recommended). This needs to be done for every piece of data you import.
Frame 2.4.1.3
Drag both your DEM and your shape file into the 2-D view.
Frame 2.4.1.4
16
2.4.2) Now, create a new watershed.
Frame 2.4.2.1
Drag your DEM file into the newly created watershed's DEM slot.
Frame 2.4.2.2
Click "generate", then drag "channels" and "basin 1" into 2-D view:
17
Frame 2.4.2.3
Or (same image, just with DEM hidden for clarity of boundaries):
18
Frame 2.4.2.4
The generated basin (green line) should fit to the actual basin (black line) almost everywhere however the network often needs to be tailored. In the above case, the basin fits well save a very thin,
but very long, spike on the North East end. In order to deal with this, the area causing the spike must be
split off.
2.4.3) First, we double click along one of the generated streams creating a node:
Frame 2.4.3.1
We then right-click the node and select "add basin". Name the basin and check if the new basin
matches more accurately than the first attempt. The results from the first trial can be hidden by going to
the 2-D view menu and un-checking "visible" for the first basin attempt.
Figure 2.3: How to hide layers & Basin 2
The matching of the watershed created by Green Kenue and the actual basin boundaries might
take multiple attempts and may require a re-clipping of the DEM file. If this continually fails, a
watershed can be generated from a completely unclipped DEM file, though this is not recommended
due to Green Kenue's memory limitations.
19
2.5 Complete Watflood map
2.5.1) To generate the Watflood map for the region:
Frame 2.5.1.1
Drag the watershed from the previous step into the Watflood map. In the properties box use
either the default settings or input the custom value. In this example, 15 km resolution was used and the
delta was selected for this resolution.
Frame 2.5.1.2
Once the values for the required grid size have been selected, make sure "Calculate FRAC from
Contributing Areas" is checked, then click the "Collect" button. When the process finishes, click the "ok"
button on the process window that comes up. With the Watflood map base in place, we now need to
make use of our ecodistrict data from step 3.
2.5.2) Import all the individual ecodistrict shape files:
20
Frame 2.5.2.1
Once we've dragged the new shape files into view (after assigning the spatial coordinate type),
the workspace look something like:
Frame 2.5.2.2
2.5.3) We now need to add these ecodistricts to the Watflood map's data sources. To do this, go
into the properties menu:
Frame 2.5.3.1
Then select the data tab, and press "add".
21
Frame 2.5.3.2
Add each of ecodistricts that touch the region you're interested in: this is done by clicking on
"Land Use Class" and entering the name of the ecodistrict layers added to the workspace previously.
Frame 2.5.3.3
2.5.4) Once this has been done for all (in this case 3) important ecodistricts, go to the tools
menu and select "map object".
22
Frame 2.5.4.1
In the map object window, all the ecodistricts you have added to the workspace should be
present. Add one (by highlighting it then clicking ok), then repeat for each other ecodistrict.
Note: Make sure that the map object added has been previously selected in the data menu
(indicated by the green check) - failure to properly select the channel being operated on will result in
incorrect maps.
Frame 2.5.4.2
The result should look similar to this after the Watflood map has been dragged into view):
23
Frame 2.5.4.3
Here, the green line indicates the basin, while the black & purple lines denote the ecodistrict
boundaries.
2.5.5) Now that the map is almost ready, however it must be normalized. In order to do this,
return to the data tab of the Watflood map's property menu and add a fake district:
Frame 2.5.5.1
Now delete this district.
24
Frame 2.5.5.2
Save the Watflood .map file.
2.6 Modify the .map file and execute BSN.exe
2.6.1) Place both bsn.exe and the newly created map file in the same directory. (Note: The map
file must have the appropriate form. In order to verify that the map file is correct, compare it's header
with a pre-existing map file that has already been used by bsn.exe - make any modifications required to
make the files have a similar form.)
Frame 2.6.1.1
25
2.6.2) Go to the command line (this is for a windows operating system), and use the "cd"
command to change directory until one is in the required folder. Once there, execute bsn.exe:
Frame 2.6.2.1
Input the .map file (and, if you have it, a par file), then your name or initials.
Frame 2.6.2.2
26
Hit enter when prompted in order to use the whole data set. If modelling in only a subsection of
the area provided for by the data you can specify that at this point. The basic parameters of the map file
you provided will be shown at this point: if everything is as expected, carry on; if not, you may need to
check your map file.
Frame 2.6.2.3
Enter 0 (and then yes) for the split unless one has data specific to this topic.
Frame 2.6.2.4
Stipulate the minimum allowable river slope, then enter through the remaining comments.
Providing there are no errors, the file that sought (new_shd.r2c) will be produced when bsn.exe
completes its run (as shown in frame 2.6.2.5).
27
Frame 2.6.2.5
28
3. MESH Land Cover Determination and CLASS File Preparation
With the drainage database file being completed, the next stage is the development of land
cover based files. The key file produced within this section is the CLASS parameter .ini file; a file that
contains land cover ratios, global position, vegetation parameters, albedo parameters, etc. All the data
required to create this file was used in chapter 2 to produce the drainage database file. As such, no
additional data needs to be collected for this part of the tutorial.
3.1 Modify the Land Cover Files Using ArcGIS
For the purposes of demonstration, here we show the process of land cover determination for
the Castle River headwater of the Oldman river using ArcMap 10.1 and Microsoft Excel 2007
3.1.1) The first step is to modify (clip) the land cover file to a form that will allow us to
determine the terrain of the basin. To begin, start up ArcMap and, using the "Add Data" button, add in
the land cover data, the basin boundary shapefile, and the individual ecodistricts that cover this basin.
Frame 3.1.1.1
29
This leads us to:
Figure 3.1: Workspace with boundary shapefile and individual ecodistricts added (the colouring of the
ecodistricts has been set to "hollow" for easier viewing).
Note: When one attempts to add the land cover data in, a warning message appears,
"Geographic Coordinate System Warning". This can be ignored by clicking the "close" button.
Figure 3.2: Workspace once land cover has been added in.
3.1.2) Select the "ArcToolbox" icon on the top ribbon:
Frame 3.1.2.1
30
We're interested in the "clip" tool (found under "Analysis Tools" > "Extract" > "Clip"):
Frame 3.1.2.2
For our purposes, the "input feature" will be the land cover data (you can simply drag and drop
the title of the land cover data set from the table of contents to the parameter of interest in the clip
window) and the "clip feature" will be our basin shape file. Set the output destination to an appropriate
choice.
Frame 3.1.2.3
31
This leads to the creation of a new, more restricted land cover data set:
Frame 3.1.2.4
There are several routes that can be taken at this point: if the catchment is fairly small and/or
the required precision of MESH output is relatively low, then the land cover data does not need to be
clipped further (one can skip directly to step 8). However, a more accurate method requires the division
of the land cover by ecodistrict and then using that data to make unique land cover schemes for each
partition.
3.1.3) To do this, we clip the already restricted land cover along the ecodistrict lines (for this
example, the land cover is clipped along ecodistrict 1019).
Frame 3.1.3.1
32
Which leads directly to:
Frame 3.1.3.2
Repeat with any other ecodistricts that cover the region of interest.
3.2 Extracting the Land Cover Data
Now that the land cover maps have been appropriately clipped along both ecodistrict and
region of interest lines, we need to actually extract the data.
3.2.1) To do so, select one of the land cover clips, in this case ecodistrict 1019, and click "Open
Attribute Table".
Frame 3.2.1.1
The land cover data we collected does not have a field for area - this must be added in order to
determine land cover ratios for CLASS.
33
Frame 3.2.1.2
To add the area field, go to the "Table Options" icon and select the "Add Field" option:
Frame 3.2.1.3
Title the new field "Area" and select "Double" for the type.
Frame 3.2.1.4
34
3.2.2) There is now a field for area in our table, however there are no values yet. In order to fill
these in, click on the "Area" banner and select "Calculate Geometry".
Frame 3.2.2.1
Click "Yes" to pass the warning(s) - make sure the property is set to "Area", the coordinate
system is selected for the data frame, and the units are set to m2.
Frame 3.2.2.2
35
Now, sort the newly updated field by "Covtype":
Frame 3.2.2.3
3.2.3) Sum together all the areas for a given Covtype - as an example here is the computation (in
the formula bar) for total area of Covtype 12 in ecodistrict 1019:
Frame 3.2.3.1
Repeat for all cover types.
3.3 Determine the Land Cover Percentages in Excel
Once the summations have been obtained, determination of the relative cover percentages is to
be undertaken. In order to make this process cleaner, set up an excel file in the following fashion (the
needed equations have been typed into the formula bar).
36
3.3.1) Copy your data into the first two columns of the table:
Frame 3.3.1.1
3.3.2) Determine the total area covered (equation in formula bar):
Frame 3.3.2.1
37
3.3.3) Declare the corresponding cover type for each Covtype number (a legend explaining
Covtypes is available in the Documentation section of Geobase's land cover sets, "Data Product
Specifications" (pdf) http://geobase.ca/geobase/en/data/landcover/csc2000v/description.html):
Frame 3.3.3.1
3.3.4) Determine the total percentage of land cover for each respective area:
Frame 3.3.4.1
Note: It is recommended to verify that the percent covers add up to 100% to make sure no
mistake was during the computations.
38
3.3.5) Collect the data into the 5 land types supported by CLASS, Broadleaf, Needleleaf, Crops,
Grass, and Urban (which cover type belongs in which category can be determined by checking CLASS's
documentation - either the full user's guide or the CLASS input/output manual):
Frame 3.3.5.1
3.3.6) Calculate the percentages for each CLASS type:
Frame 3.3.6.1
Repeat for each other ecodistrict that intersects the region of interest.
3.4 Adjust the CLASS Input Files
In order to run MESH (this is assuming the Ostrich is used to allow for multiple runs with no
breaks or user input) there are two forcing files required for the CLASS section:
MESH_parameters_CLASS.ini and MESH_parameters_CLASS.tpl. They are identical save for the
parameters that are to be varied through the course of the simulation runs.
39
3.4.1) We'll start by the construction of the .ini file - template file creation will be explained in
later steps. There are two ways to go about beginning the creation of a CLASS .ini file: copy an old one
or build one from scratch. It is recommended to copy & paste as it will save time, though if old files are
not available a new one can be constructed from the ground up by following the instructions of either
the CLASS in/out document or the CLASS manual. Regardless of the method used, all parameters must
be filled in with either recommended values (this typically works fine) or measured/output values
specific to your region. This leads to a document that looks like:
Frame 3.4.1.1
40
Explanation of frame 3.4.1.1 (For much more in-depth information see "CLASS I-O.doc" or
"CLASS_v3_4_Documentation.pdf"):
Lines 1-3: These lines are for commentary - typically the drainage basin being worked on is indicate in
line one, the author in line two, and the institution in line three.
Line 4: The first two values indicate the coordinates of the location of the basin in terms of latitude and
longitude and must be set according to the location of one's simulations. The next refer to the reference
heights for air temperature/humidity, wind velocity, and atmospheric blending respectively - the values
in these columns typically do not need to be adjusted. The next two values are always left as -1.0 and 1.
Finally, the last two columns indicate parameters to be varied and number of ecodistricts (or number of
land cover divisions). These must be adjusted according to one's region.
Lines 5-19: These represent the parameters for one ecodistrict, and, as such, these parameters must be
adjusted and re-entered for all the ecodistricts. The most crucial elements (ie, the elements that do not
take on standardized values) are in line 5 and line 13. The first five elements of line 5 refer to the
percentage land cover or each of CLASS's land types: Needleleaf Forest, Broadleaf Forest, Crops, Grass,
and Urban, in that order. Input the values obtained from the Excel land cover file, each rounded to 3
decimal places. These 5 values MUST add up to 1. The final value in line 13 keeps count of how many
ecodistricts have been entered into your .ini file: simply put in 1 for the first district, 2 for the second,
and so on.
Lines 50-53 (if you just had one ecodistrict, 20-23): Additional CLASS run parameters that one should not
have to adjust.
With the CLASS .ini file completed, we can progress onto the preparation of other minor
required files for MESH.
41
4 Production of Remaining MESH Files
The creation of the two key MESH input files has been completed in the first two sections; this
final section is concerned with the development of the remaining input files. Although there is a large
number of files that are created in this part, the majority of these files require little preparation.
Organization is the crucial piece of this step - unorganized files make successfully running MESH difficult.
4.1 Required Data and Executables
4.1.1) In order prep the remaining files & run MESH, there is a collection of needed files:
- Drainage database
- CLASS .ini
- Meteorological forcing data (humidity, longwave radiation, pressure, rain,
shortwave radiation, temperature, and wind) from NARCCAP
- ANUSPLIN precipitation data
- Incoming streamflow data
- Regional reservoir data (optional)
- Ostrich (including all .bat, .exe, and .txt files)
- MESH (including all .bat, .txt, and .exe files)
For MESH, there are several files needed in order to run the simulations: SA_MESH.exe,
SA_MESH_debug.exe, minmax_parameters.txt, and run_mesh.bat.
Ostrich requires many files in order to run: Ostrich.exe, OstrichMonitor.exe, Ostrich.bat, OSTMESH.bat, OstIn.txt, as well as all the files needed for MESH.
4.2 Pre-run organization
There are many files required for a successful run of MESH, as such good organization is
incredibly important if one wants to avoid missing files, forgetting to update values, or losing output.
Although any organizational system can work, I'll demonstrate a layout that can be used to obtain
functional simulations as an example.
4.2.1) There are two key directories that are created: "Models" and "Simulations" (in this
tutorial, I use "Tutorial Simulations").
Frame 4.2.1.1
42
The "Models" folder is easy to set up, you only need the MESH executable and its debugger;
SA_MESH.exe & SA_MESH_debug.exe, respectively.
Frame 4.2.1.2
In the "Simulations" folder, create a folder for each catchment being studied:
Frame 4.2.1.3
4.2.2) Within each catchment folder being studied, a minimum of two directories should be
created: one for the forcing files that MESH will be using, the other for run information. If one is
planning to run either multiple instances of MESH at once or just desires to break the entire process into
smaller partitions, than the creation of multiple run files is required. As an example, see the frame
below:
Frame 4.2.2.1
43
Fill the "Forcing Files" folder with the meteorological forcing files.
Frame 4.2.2.2
For the purposes of this tutorial we'll work on developing the "ost_1_5000" (the 1_5000 was
chosen since this simulation set is designed to have 10000 runs split into two different groups) directory,
completing the other directory is identical, save the different name. Within "ost_1_5000", two
additional directories must be created: "BASINAVG1" (this is where all run results will show up) and
"ost" (for all the Ostrich files).
Frame 4.2.2.3
No files need to be placed in "BASINAVG1" prior to runs taking place (existing files will be
overwritten during a MESH run).
Frame 4.2.2.4
44
We don't need to deal with the "ost" folder quite yet, this only comes into play when we're
attempting multiple runs of MESH via Ostrich.
4.2.3) To complete the preparations for single runs of MESH we only need to add in all the input
files. To begin, copy the files from the "forcing files" directory and paste them is "ost_1_5000":
Frame 4.2.3.1
Note that the basin_rain.r2c file shown in this frame is just basin_pcp_ANUSPLIN.r2c renamed
so MESH will recognize the file as precipitation data (MESH won't accept basin_pcp_ANUSPLIN.r2c as a
valid name for precipitation data).
Now, add in the drainage database and MESH_parameters_CLASS.ini files prepared in the earlier
stages of this tutorial along with the remaining two MESH files: run_mesh.bat &
minmax_parameters.txt. (run_mesh.bat will need to be modified - this will be dealt with in step 16).
Frame 4.2.3.2
45
At this point, all of the files added into the directory should be complete (save run_mesh.bat,
which must be modified).
4.2.4) The other files that we will add must be modified or created from scratch - assuming one
has access to examples of these files, copy and paste the examples into this directory. If not, generate
blank files of the correct extension:
Frame 4.2.4.1
With that done, all of the files we need to run MESH are in place, we just need to finalize their
preparation.
4.3 Minor file construction
The files within this section are referred to as "minor" due to the fact that they are: a) simple to
construct, b) require little to no customization between runs, and c) typically quite short. Despite the
comparatively small amount of information present in these files, the first three are required for a
successful run of MESH while the last one is required for a successful of Ostrich.

4.3.1) Soil Levels
This file determines the number of soil layers present and the thickness of each of these
layers. The layout of the file is as in frame 4.3.1.1.
46

Frame 4.3.1.1
The first column indicates depth of a given layer, while the second indicates cumulative
depth. 3-4 layers is typical and extending below 5 meters is usually not necessary. Plug in the
values that are specified to your region, or just use the general parameters seen here.
4.3.2) MESH Input Streamflow
The most complicated of all the "minor" files, the input streamflow requires forcing data for
every time step MESH runs. This data can be collected either from measurements or model
output - varying from project to project based on data availability.
Frame 4.3.2.1
The first three lines provide the header to the file: line 1 indicates the number of input
streamflow columns (hydrometric gauges); line 2 indicates number of data points, time
interval between data points, location of gauge, and start date in year, day, hour form
(typically start date is the only header part that needs to be changed); line 3 is a character
string that should be used to name and/or describe the basin being used.

4.3.3) MESH Input Reservoirs
Another very simple file, this text document gives MESH information on the reservoirs
within the region of interest. Unless there are some unusually large or otherwise important
reservoirs present, one can simply use the default values shown in the frame below:
Frame 4.3.3.1
47

4.3.4) Index
This file indicates the number of the run you're going to start on minus one (eg. if you're
going to be running your 1st run, this would be set to 0):
Frame 4.3.4.1
The number here determines the name of the output file - this is incredibly important for
automatic repeated runs of MESH as it prevents the continual overwriting of the output file.
4.4 MESH input run options
4.4.1) This document allows for significant customization of the MESH run process, however, for
our purposes customization is not a central need. Because of this, we can essentially ignore the control
flag section (up to and including line 27 of frame 4.4.1.1), as well as the output sections (lines 28 through
37), leaving them to default values.
Frame 4.4.1.1
The only lines we need to adjust are the final two in frame 4.4.1.1 - adjust these to the start and
end date in the form year, day, hour, minute.
48
Note: For a complete description of control flags and how to use them to customize MESH, look to the
full MESH documentation.
4.5 MESH hydrology parameters
4.5.1) The final .ini final that must be prepped, the hydrology parameters file is another case of a
heavily customizable document that we'll leave running almost purely on default values:
Frame 4.5.1.1
Once again, the first 23 lines in frame 4.5.1.1 will be left alone completely. In line 24, set the
number of GRUs to the number of ecodistricts that cover the basin (in this case, we're still working with
the Castle River catchment, which has 3 covering ecodistricts). Lines 27-35 should have a number of
columns equal to the number of GRUs. The values in lines 30-35 should be left as the default values
shown here, while the values in lines 27-29 can be set to any value between 0 and 1.
4.6 .BAT file Modification
4.6.1) The final step in preparing MESH for single run use is the modification of the
run_mesh.bat file. The unmodified file should look very similar to frame 4.6.1.1.
49
Frame 4.6.1.1
The only thing that needs to be modified is the highlighted line (line 10 of frame 4.6.1.1) change the path to match the directory where SA_MESH.exe and SA_MESH_debug.exe are located on
the computer.
Note: Lines 15 on deal with the copying of MESH output to another file so subsequent runs don't
overwrite the output from the previous run. Technically, this isn't necessary to keep for single runs of
MESH, but it is best to leave it in the file.
4.7 MESH test run
It's time to actually run the program! We'll be running MESH from the command line as this
allows one to receive error messages if things go wrong.
50
4.7.1) Open the command line and change directory so that the directory being operated on
contains run_mesh.bat.
Frame 4.7.1.1
Type "run_mesh.bat" onto the prompt and hit enter, if things go well the entire simulation will
run over the prescribed date range and, at the end, will output "Program has terminated normally."
Frame 4.7.1.2
51
4.7.2) If, however, something goes wrong, an error message will appear and the simulation
won't run:
Frame 4.7.2.1
MESH will output which file (or files) are missing - in this case basin_shortwave.csv was missing
from the directory.
4.7.3) To check the output, view the BASINAVG1 directory (the file we're interested in is the one
highlighted below).
Frame 4.7.3.1
52
5. Preparation of Ostrich and its files
Optimization Software Toolkit for Research Involving Computational Heuristics, OSTRICH, is a
multi-algorithm optimization and parameter estimation tool developed at the University of Waterloo.
Created as a model-independent program, Ostrich allows researchers and field-practitioners to
automate model calibration and design optimization processes, taking the place of manual trial-anderror approaches.
For the purposes of MESH hydrology modelling, Ostrich is used to provide a system for
automatically varying simulation parameters from run to run. The range of these parameters can be
specified and the parameter values for each individual run can be generated using any method - Ostrich
will accept the values so long as they are within the specified range.
5.1 Ostrich preparation
5.1.1) Firstly, before Ostrich can be implemented two things must be done: selection of the free
parameters that are to be varied, and generation of a pseudo-random number set referring to different
combinations of the free parameters. Depending on the goal of the project, these parameters can be
chosen to study a certain aspect of the MESH system. For our example, the parameters chosen are as
follows:
Table 5.1: MESH Parameters to be varied by Ostrich for the Castle River Catchment
GRUs
Sub-surface
GRU 1
(Crowsnest
Mountains)
Sub-surface
GRU 2
(Blairmore
Foothills)
Sub-surface
GRU 3
(Waterton
Mountains)
Parameters
ZSNL1
ZPLS1
ZPLG1
XSLOPE1
WFCI1
SDEP1
ZSNL2
ZPLS2
ZPLG2
XSLOPE2
WFCI2
SDEP2
ZSNL3
ZPLS3
Parameter definition
Limiting snow depth below which coverage is < 100% [m]
Maximum water ponding depth for snow-covered areas [m]
Maximum water ponding depth for snow-free areas [m]
Average overland slope [-]
Horizontal conductivity at surface [m/s]
Permeable depth of the soil column [m]
Limiting snow depth below which coverage is < 100% [m]
Maximum water ponding depth for snow-covered areas [m]
Maximum water ponding depth for snow-free areas [m]
Average overland slope [-]
Horizontal conductivity at surface [m/s]
Permeable depth of the soil column [m]
Limiting snow depth below which coverage is < 100% [m]
Maximum water ponding depth for snow-covered areas [m]
Parameter ranges
0.030 - 1.0
0.005 - 0.5
0.005 - 0.5
0.001 - 0.5
0.00001 - 0.03
1.1 - 4.1
0.030 - 1.0
0.005 - 0.5
0.005 - 0.5
0.001 - 0.5
0.00001 - 0.03
1.1 - 4.1
0.030 - 1.0
0.005 - 0.5
ZPLG3
XSLOPE3
WFCI3
SDEP3
WF_R2*
Maximum water ponding depth for snow-free areas [m]
Average overland slope [-]
Horizontal conductivity at surface [m/s]
Permeable depth of the soil column [m]
River roughness [m1/2/s]
0.005 - 0.5
0.001 - 0.5
0.00001 - 0.03
1.1 - 4.1
0.40 – 1.0
53
If we were dealing with a basin covered by only 2 ecodistricts (Crowsnest, for example), then the
third set of parameters would not exist. Once the parameters (and their ranges) have been selected, a
set of values must be generated. This can be done using any method one prefers; for the purposes of
this example the values were generated using a Latin Hypercube Sampling scheme - see the references
sections for further reading.
5.1.2) Organization of the "ost" directory should be as follows:
Frame 5.1.2.1
The three folders, "best", "OUTPUT", and "OUTPUTCalibration" and their contents should be
simply copied and pasted - staying unmodified; similarly, function_out.txt, Ns.txt, OST-MESH.bat,
Ostrich.bat, Ostrich.exe, OstrichMonitor.exe, and save_best.bat should remain untouched.
MESH_parameters_CLASS.ini and MESH_parameters_hydrology.ini should have been created earlier in
this tutorial. This leaves only three files to be worked on: MESH_parameters_CLASS.tpl,
MESH_parameters_hydrology.tpl, and ostIn.txt.
54
5.1.3) The template files (.tpl) are identical to their .ini counterparts within one small exception:
all parameters being varied are changed from a specific numeric value to the name listed in the
"Parameter" column of the above table (eg. ZNSL1). In the case of the Castle River basin:
Frame 5.1.3.1
As one can see, 9 values are replaced in this template file, 3 per ecodistrict, and this is the only
modification required to complete the template file.
55
Similarly, the hydrology template file:
Frame 5.1.3.2
Again, 3 parameters per ecodistricts have been replaced, along with a single general parameter
in line 9, the river roughness factor.
56
5.1.4) Once these replacements have been made, the ostIn.txt file is the final Ostrich file that
must be worked on:
Frame 5.1.4.1
This image of the header chunk of the ostIn file shows the space where one declares all the
parameters that are to be varied - in this case there are the six parameters per ecodistrict plus the river
roughness parameter. The only pieces of the header that really need to adjusted are the "lower" and
"upper" columns (to whatever boundaries are appropriate for your simulations) as well as the final
number in each row (ie, for line 13 of the above image ".2"); this number indicates the precision of the
values to be inserted into the .ini files. The precision cannot be set too high or values being varied by
Ostrich will start to collide with other variables in the .ini files, causing the program to fail.
Frame 5.1.4.2
57
5.1.5) Once the header file has been completed, put the pseudo-random values that are to be
varied in the above form: the first column corresponds to the first parameter declared in the header
section of ostIn and so on. Each row indicates one simulation, so if one wishes to do 5000 runs, 5000
rows of values must be created.
Frame 5.1.5.1
The final section of the ostIn file does not need to be altered and can be left as seen in frame
5.1.5.1.
With that, everything is ready to go for the full simulation set.
5.2 Final test run
Before the full 5, 10, or 15 thousand run simulation is started, it is advisable to test the Ostrich
setup via a 5 or 10 run simulation.
58
5.2.1) To do so, simply delete all the simulation rows in the ostIn file save 5. Using the command
line, go to the "ost" directory:
NOTE: Before running the simulation, make sure that "index.txt" is equal to 0 (or whatever number run
you want to start at minus one)
Frame 5.2.1.1
Now, execute "Ostrich.bat".
Frame 5.2.1.2
If the Ostrich monitor starts displaying values (as above), the files have most likely been
completed and arranged correctly - once the trial is finished, go ahead and start up the full simulation!
59
6. Common Errors
Through the course of using MESH, there are many places where errors can occur. The purpose
of this section is to help one move past common obstacles as quickly as possible. There are many other
issues that can come up, however these must be dealt with on a case by case basis - see the Ostrich,
MESH, or CLASS documentation for further information.
6.1 Coordinate Issues
One of the most common issues that shows up when dealing with the shape files in ArcMap 10.1
is the existence of shape files with coordinate systems that are not compatible with GreenKenue. For
example if the red box outlined in frame 6.1.1.1 were to be in units of meters (as opposed to decimal
degrees), the shape file being worked on would not be able to be opened in GreenKenue making it
impossible to verify the area of the generated basin.
Frame 6.1.1.1
The simplest way to deal with coordinate issues is to adjust the data frame coordinate system.
This can be done by selecting the "Properties" menu after right clicking "Layers", as shown in frame
6.1.1.2.
60
Frame 6.1.1.2
This leads to the "Data Frame Properties" window, where the correct coordinate system can be
selected (in this example, "North America" > "NAD 1983" was used).
Frame 6.1.1.3
61
6.2 bsn.exe Crashes
In section 2.6, a description of using bsn.exe to modify the .map file produced in GreenKenue to
its final form is outlined. Unfortunately, bsn.exe is prone to crashing over minor syntax issues present in
the .map file. Because these syntax issues can pop up anywhere in one's .map file, they must be dealt
with on a case by case basis. In order to expedite the process of finding the bugs in one's file, download
Winmerge (winmerge.org). Winmerge is a tool that allows for the comparison of two documents side by
side - making it easy to notice syntactic differences between documents. An example of the interface is
demonstrated in frame 6.2.1.1.
Frame 6.2.1.1
For best results, obtain a .map file that can be processed by bsn.exe and use that as a metric for
other .map files produced. In the above case, the right .map file is a two district representation of a
region (Castle River), whereas the left file is a single district representation.
Frame 6.2.1.2
62
The .map file on the right was originally failing when it was running on a "classCount" of 1. To
match the other file more closely, this was adjusted to 2 and an additional blank district was added to
the bottom of the file (see the group of zeros in the bottom right corner of frame 6.2.1.2). Adjustments
such as this that make the new .map file more like the functional .map file make it much easier to get
bsn.exe running without errors.
6.3 run_mesh.bat Errors
Another error that occurs frequently (especially if one is using multiple computers to run
simulations) is that the file path specified in run_mesh.bat cannot be found on a given machine. This
leads to an error similar to the one displayed in frame 6.3.1.1.
Frame 6.3.1.1
There are two steps to resolving this fault: 1) check to make sure there are no typos present and
2) putting quotation marks around the specified path.
63
Frame 6.3.1.2
Frame 6.3.1.2 demonstrates this principle on line 10. The quotation marks are always needed if
there are spaces present in the directory path (eg. "Documents and Settings").
6.4 Ostrich Quits Prematurely
When one moves to doing multiple runs via Ostrich, occasionally the Ostrich Monitor comes up
completely blank and the message "Ostrich is Finished" pops up immediately. This situation is
demonstrated on the next page, in frame 6.4.1.1.
64
Frame 6.4.1.1
Typically, this is caused by syntactical errors in the ostIn file - the most common being missing a
return on the third line after "GCOP", as shown in frame 6.4.1.2:
Frame 6.4.1.2
In this case, add a return before "ModelExecutable". If this is not the location of the error, use
Winmerge to check both the header and footer of this file against those of a known working file.
65
7. Acknowledgements
This tutorial was prepared as one of the milestones related to the employment of the first
author at the Global Institute for Water Security (www.usask.ca/water) during summer 2013. The
financial support for this term was provided by Canada Excellence Research Chair in Water Security at
the University of Saskatchewan.
66
8. References and Further Reading
Davison, B., Holman D., Salisbury, A., Thompson, C., Fong, C., Wilson R., Toth, B., Bilodeau, D., Marsh, C.,
Liu, A., Armstrong, R., and Seglenieks, F. (2009). MESH Training Manual.
Matott, L.S. OSTRICH: An Optimization Software Tool; Documentation and User’s Guide. Version 1.6.
State University of New York at Buffalo Department of Civil, Structural and Environmental
Engineering.
McKay, Michael D., Richard J. Beckman, and William J. Conover. (1979). Comparison of three methods
for selecting values of input variables in the analysis of output from a computer
code. Technometrics, 21 (2), 239-245.
Mekonnen, M.A., Wheater, H.S., Chun, K.P., Nazemi, A., Ireson, A.M. (2013). Hydrologic-Land Surface
modelling of streamflow using climate model outputs in the headwaters of Saskatchewan River
Basin, Canada. Under Review, School of Environment and Sustainability and the Global Institute
for Water Security, University of Saskatchewan.
Pietroniro A. and Soulis, E.D. (2003). A hydrology modelling framework for the Mackenzie GEWEX
programme. Hydrological Processes, 17(3), 673-676. ISSN 1099-1085.
Pietroniro, A., Fortin, V., Kouwen, N., Neal, C., Turcotte, R., Davison, B., Verseghy, D., Soulis, E.D.,
Caldwell, R., Evora, N. and Pellerin, P. (2007). Development of the MESH modelling system for
hydrological ensemble forecasting of the Laurentian Great Lakes at the regional scale. Hydrology
and Earth System Sciences, 11(4):1279-1294.
Snelgrove K.R., Soulis E.D., Seglenieks F.R., Kouwen N. (2005). The application of hydrological models in
MAGS: Lessons learned for PUB. In Prediction in Ungauged Basins: Approaches for Canada's Cold
Regions, Spence C, Pomeroy, JW, Pietroniro A (eds). Canadian Water Resources Association:
Ottawa, ontario; 139 - 164.
Soulis E.D., Seglenieks F.R. (2007). The MAGS integrated modeling system. In Cold Regions Atmospheric
and Hydrologic Studies: the Mackenzie GEWEX Experience, hydrologic Processes, vol 2, Woo MK
(ed). Springer-Verlag: Berlin Heidelberg; 445 - 474.
Soulis, E.D., Kouwen, N., Pietroniro, A., Seglenieks, F.R., Snelgrove, K.R., Pellerin, P., Shaw, D.W. and
Martz, L.W. (2004). A framework for hydrological modelling in MAGS. In: Prediction in Ungauged
Basins: Approaches for Canada.s Cold Regions. Edited by Spence, C., J.W. Pomeroy and A.
Pietroniro (eds.), CWRA ACRH Press, Ontario, Canada.
Soulis, E.D., Snelgrove, K.R., Kouwen, N., Seglenieks, F., Verseghy, D.L. (2000). Towards closing the
vertical water balance in Canadian atmospheric models: coupling of the land surface scheme
CLASS with the distributed hydrological model WATFLOOD. Atmosphere-Ocean , 38 (1), 251-269.
Verseghy, D.L. (1991). CLASS: A Canadian Land Surface Scheme for GCMs. I. Soil Model. International
Journal of Climatology, 111-133.
67
Verseghy, D.L., McFarlane, N.A., Lazare, M. (1993). CLASS: A Canadian Land Surface Scheme for GCMs. II.
Vegetation Model and Coupled Runs. International Journal of Climatology, 347-370.
Verseghy, D.L. (2008). The Canadian Land Surface Scheme: Technical Documentation - Version 3.4.
Climate Research Division, Science and Technology Branch, Environment Canada.
68
69