Page tree

MESH - A Community Hydrology - Land Surface Model


Skip to end of metadata
Go to start of metadata

This file contains model configuration options.

Page contents:

Overview

MESH_input_run_options.ini contains four sections: control flags, diagnostic point output selection, output directory, and simulation run times.

Sample files

A sample file configured to run the Soil-Vegetation-Snow (SVS) land surface scheme in a point-mode using driving data read from the CLASS MET format forcing file:

MESH_input_run_options.ini
MESH run options input file
##### Control flags #####
----#
    8 # Number of control flags
BASINFORCINGFLAG         met start_date=1994100101 hf=60
SHDFILEFLAG            2
INPUTPARAMSFORMFLAG      only txt
SOILINIFLAG            0
NRSOILAYEREADFLAG      3
RUNMODE                  runsvs noroute
DIAGNOSEMODE             on
TIMESTEPFLAG           5
##### Diagnostic point output selection #####
----#
    0 # Number of output points
---------#
         1 #1 Grid number
         1 #2 GRU (if applicable)
output     #3 Output directory
##### Output directory #####
---------#
output     # Output directory for total-basin files
##### Simulation run times #####
---#---#---#---#
   0   0   0   0 # Start year, day, hour, minutes
   0   0   0   0 # Stop year, day, hour, minutes

A sample file configured to run the default Canadian Land Surface Scheme (CLASS) with the default channel and reservoir routing scheme (WF_ROUTE) in a distributed mode, with basin configuration defined in r2c format and reading driving data in r2c format:

MESH_input_run_options.ini
MESH run options input file
##### Control flags #####
----#
   10 # Number of control flags
HOURLYFLAG            60
BASINRAINFLAG          1
BASINLONGWAVEFLAG      1
BASINSHORTWAVEFLAG     1
BASINTEMPERATUREFLAG   1
BASINWINDFLAG          1
BASINPRESFLAG          1
BASINHUMIDITYFLAG      1
SHDFILEFLAG            1
SOILINIFLAG            1
##### Output Grid selection #####
----#
    0 # Number of output grid points (5 points maximum)
---------#
         7 #1 Grid number
         1 #2 Land class
BASINAVG1  #3 Output directory
##### Output Directory #####
---------#
BASINAVG1  # Output Directory for total-basin files
##### Simulation Run Times #####
---#---#---#---#
2004 153   0   0 # Start year, day, hour, minutes
2005 274   0   0 # Stop year, day, hour, minutes

Sections

Control Flags

The control flags are used to customize the functionality of MESH.

  • BASINFORCINGFLAGThe BASINFORCINGFLAG control flag specifies the input format for driving data forcing files, as well as details about the data.
  • NRSOILAYEREADFLAGThe NRSOILLAYEREADFLAG control flag controls the number of layers to read from MESH_parameters_CLASS.ini or MESH_parameters.txt when reading soil-related parameters and initial values.
  • OUTFILESFLAGThe OUTFILESFLAG control flag is used to activate configurable outputs specified via the 'outputs_balance.txt' input file.
  • PRINTSIMSTATUSThe PRINTSIMSTATUS control flag provides options to control if and how the simulation summary is printed to screen.
  • SHDFILEFLAGThe SHDFILEFLAG control flag specifies the basin information file format.

Information on the following control flags may be out-of-date.

HOURLYFLAG:

Set HOURLYFLAG to 60 for hourly forcing data, 120 for two hourly forcing data etc..
Set HOURLYFLAG to 30 for 30 minute forcing data.
By default, HOURLYFLAG = 30.

Please note: This option simply disaggregates the forcing files to a half-hourly timestep since the model runs at a half-hourly timestep. If you want to run the model at a daily timestep, perhaps MESH isn't the model for you to use. If you are using this option to disaggregate your forcing files from something more than 6-hourly to half-hourly, then you should probably pre-process your forcing files outside of MESH to a half-hourly timestep. This will give you more control over the forcing files. For example, incoming shortwave radiation has a diurnal cycle that would not be captured by disaggregating daily forcing files to half-hourly files.

IDISP:

If IDISP = 0, vegetation displacement heights are ignored, because the atmospheric model considers these to be part of the “terrain".
If IDISP = 1, vegetation displacement heights are calculated.
By default, IDISP = 1.

IZREF:

If IZREF = 1, the bottom of the atmospheric model is taken to lie at the ground surface.
If IZREF = 2, the bottom of the atmospheric model is taken to lie at the local roughness height.
By default, IZREF = 1.

ISLFD:

If ISLFD = 0, DRCOEF is called for surface stability corrections and the original GCM set of screen-level diagnostic calculations is done.
If ISLFD = 1, DRCOEF is called for surface stability corrections and SLDIAG is called for screen-level diagnostic calculations.
If ISLFD = 2, FLXSURFZ is called for surface stability corrections and DIASURF is called for screen-level diagnostic calculations.
By default, ISLFD = 2.

IPCP:

If IPCP = 1, the rainfall-snowfall cut-off is taken to lie at 0 dc.
If IPCP = 2, a linear partitioning of precipitation between rainfall and snowfall is done between 0 dc and 2 dc.
If IPCP = 3, rainfall and snowfall are partitioned according to a polynomial curve between 0 dc and 6 dc.
By default, IPCP = 1.

ITC, ITCG, ITG:

ITC, ITCG and ITG are switches to choose the iteration scheme to be used in calculating the canopy or ground surface temperature respectively.
If the switch is set to 1, a combination of secant and bisection methods is used;
if to 2, the Newton-Raphson method is used.
By default, ITC = 2, ITCG = 2, ITG = 2.

IWF:

If IWF = 0, only overland flow and baseflow are modelled, and the ground surface slope is not modelled.
If IWF = 1, WATROF - calculations of overland flow and interflow are performed based on approximations of Richards' equation.
If IWF = 2, PDMROF - surface runoff calculations for "fill and spill" processes in the prairie pothole region.
By default, IWF = 1.

IPAI, IHGT, IALC, IALS, IALG:

If IPAI, IHGT, IALC, IALS and IALG are zero, the values of leaf are index, vegetation height; canopy albedo, snow albedo and soil albedo respectively calculated by class are used.
If any of these switches is set to 1, the value of the corresponding parameter calculated by class is overridden by a user-supplied input value.
By default, IPAI = 0, IHGT = 0, IALC = 0, IALS = 0, IALG = 0.

RELFLG:

If RELFLG = 0, any configuration file is read that matches the file name in the open statement.
If RELFLG = 1, only configuration files whose version matches the release of mesh_driver are read.
The program stops if the two strings do not match. This flag is not applicable to run_options.ini, where this flag may be reset).
By default, RELFLG = 1.

RESUMEFLAG:

If RESUMEFLAG is 0, the user doesn't want to use the resume file.
If RESUMEFLAG is 1, the user wants to run the resume file.

By default, RESUMEFLAG = 0

For the first run, user needs to use  ONLY SAVERESUMEFLAG set to 1

Then for consecutive runs, both RESUMEFLAG and SAVERESUMEFLAG need to be set to 1

Note: each runs need to be saved in different BASINAVG files.

SAVERESUMEFLAG:

If SAVERESUMEFLAG is 0, the user doesn't want to make the resume file.
If SAVERESUMEFLAG is 1, the user wants to make the resume file.
By default, SAVERESUMEFLAG = 0.

For the first run, user needs to use  ONLY SAVERESUMEFLAG set to 1

STREAMFLOWFLAG:

IF STREAMFLOWFLAG = 0, MESH will output a daily streamflow file only.
IF STREAMFLOWFLAG = 1, MESH will output daily and half-hourly streamflow files. (Or a streamflow file showing streamflow for each timestep if your timestep is not half-hourly.)
By default, the STREAMFLOWFLAG = 0.

SUBBASINFLAG:

IF SUBBASINFLAG= 0, calculations will be made for all grid squares.
IF SUBBASINFLAG= 1, calculations will only be done for grid squares that are in the watersheds of the locations listed in the streamflow files.
By default, the SUBBASINFLAG= 0.

INTERPOLATIONFLAG:

Flag for forcing data interpolation at intermediate time steps when the time interval of the forcing data is greater than 30 minute.
If INTERPOLATIONFLAG = 0, there will not be forcing data interpolation at 30 minute intervals (MESH model time step) irrespective of the forcing data time intervals.
If INTERPOLATIONFLAG = 1, there will be linear forcing data interpolation between consecutive data values.
By default, the INTERPOLATIONFLAG = 0

FROZENSOILINFILFLAG:

If FROZENSOILINFILFLAG =1, the frozen soil infiltration algorithm is used to partition snow melt into frozen soil infiltration and direct runoff based on the parametric equation developed by Gray et al, 2001.
If FROZENSOILINFILFLAG =0, the official version of CLASS handles all snow melt infiltration. Please refer to the CLASS manual for more details.
By default, the FROZENSOILINFILFLAG = 0

Please note: The implementation of frozen soil infiltration is a work in progress. The current implementation is meant to be a temporary measure until we can properly implement a version into CLASS. One drawback of the current implementation is that it can only be used in hindcasting mode. This limitation is due to the fact that you need to know how long the snow-melt period was for the simulation. More information about the current implementation can be found in this document: FROZEN.pdf.

AUTOCALIBRATION FLAG:

If AUTOCALIBRATION FLAG >= 1, MESH will provide options for DDS autocalibration to pre-empt (using PREMPTIONFLAG) if the current trial is worse than the best trial found so far, and to choose available objective functions (using the OBJFNFLAG). The value of the AUTOCALIBRATION FLAG is used to exclude part of streamflow data in the objective function calculation (spin-up period).
If AUTOCALIBRATIONFLAG = 0, DDS autocalibration can be set with out pre-emption option and using an externally calculated objective function value.
By default, the AUTOCALIBRATION FLAG = 0

PREEMPTIONFLAG:

If PREEMPTIONFLAG = 1, pre-empt MESH simulation if the current trial is worse than the best trial found so far. AUTOCALIBRATION FLAG needs to be greater than or equal to 1 for the PREEMPTIONFLAG to be on.
If PREEMPTIONFLAG = 0, no pre-emption
By default, PREEMPTIONFLAG = 0

OBJFNFLAG:

If OBJFNFLAG = 1, the objective function is calculated as the sum of absolute values of the differences between sorted (ranked) simulated and observed stream flow time series.
If OBJFNFLAG = 0, the objective function is calculated as the sum of absolute values of the differences between simulated and observed stream flow time series.
By default, the OBJFNFLAG = 0

R2COUTPUTFLAG:

If R2COUTPUTFLAG = 1, R2C ascii file will be written for user specified variables (list of variables will be read from r2c_output.txt file).
If R2COUTPUTFLAG = 0, R2C ascii file will not be written
By default, the R2COUTPUTFLAG = 0

SOILINIFLAG:

If SOILINIFLAG = 0, Soil percentage values will be read from MESH_parameters_CLASS.ini file and MESH will stop if sum of soil percentages is greater than 100 %
If SOILINIFLAG = 1, Soil percentage values will be read from MESH_parameters_CLASS.ini file and MESH will use the specified values even if sum of soil percentages is greater than 100 %
If SOILINIFLAG = 2, Soil percentage values will be read from MESH_parameters_CLASS.ini file and MESH readjusts the values in favour of sand if sum of soil percentages is greater than 100 %
If SOILINIFLAG = 3, Soil percentage values will be read from MESH_parameters_CLASS.ini file and MESH readjusts the values in favour of clay if sum of soil percentages is greater than 100 %
If SOILINIFLAG = 4, Soil percentage values will be read from MESH_parameters_CLASS.ini file and MESH readjusts the values proportionally if sum of soil percentages is greater than 100 %
If SOILINIFLAG = 5, Soil parameter values will be directly read from soil.ini file
by default, the SOILINIFLAG = 0

Diagnostic point output selection

Enabling this section writes significant data to file, and significantly impedes model run-time performance. It is only recommended to activate these outputs for legacy purposes, or to diagnose outputs that are not available using the OUTFIELDSFLAG/OUTFILESFLAG control flag (configured with outputs_balance.txt).

Output points can be specified by grid and GRU to print detailed diagnostic information from certain process modules. There is no limit to the number of allowable outputs points, but limiting outputs points is recommended, as the diagnostic outputs create very large files.

An output folder for each point must be specified in the third line of the section. The folder must already exist, or the program will abort with an error. The folder name cannot contain any whitespace, such as tabs or spaces.

To disable the diagnostic output selection, set the "Number of output points" to zero.

MESH_input_run_options.ini (excerpt)
##### Diagnostic point output selection #####
----#
    0 # Number of output points
---------#
         1 #1 Grid number
         1 #2 GRU (if applicable)
output     #3 Output directory

Output directory

The output directory folder name must be padded to 10 spaces if the folder name is less than 10 characters. The folder name cannot contain any whitespace, such as tabs or spaces.

The output directory is where general model outputs are saved. The folder must exist before running a simulation, or the program will abort with an error. The folder name is limited to 10 characters and cannot contain any whitespace, such as tabs or spaces.

MESH_input_run_options.ini (excerpt)
##### Output directory #####
---------#
output     # Output directory for total-basin files

To create outputs in the same location as the program, alongside the input files, set the folder name to a single period ".":

MESH_input_run_options.ini (excerpt)
##### Output directory #####
---------#
.          # Output directory for total-basin files

Simulation run times

MESH versions prior to r1333 require each of the numbers in the simulation start and stop times to be occupy 4 spaces. MESH version r1333 and later remove this requirement, such that the spacing of the 4 numbers in each line is read using free-format. More information on fixed-formatting is here.

The simulation start and stop times are specified in the last two lines of the file. They specify the year, day of year, hour in day (0-23), and minutes (must be divisible by the model time-step). The day of year must consider if the specified year is a leap-year. For reference, a table of day of year in a regular year is available here, while a table of day of year in a leap-year is available here.

More information on the simulation start and stop times, and how the simulation stop time should be specified is available here.

MESH_input_run_options.ini (excerpt)
##### Simulation run times #####
---#---#---#---#
2012 152   0   0 # Start year, Day of year, Hour in day (0-23), Minutes (must be divisible by the model time-step)
2015   1   0   0 # Stop year, Day of year, Hour in day (0-23), Minutes (must be divisible by the model time-step)

Common overrides:

  • If all fields in the simulation start date are zero, the simulation will begin from the first frame of driving data
  • If all fields in the simulation stop date are zero, the simulation will run until it runs out of driving data
MESH_input_run_options.ini (excerpt)
##### Simulation run times #####
---#---#---#---#
   0   0   0   0 # Start year, Day of year, Hour in day (0-23), Minutes (must be divisible by the model time-step)
   0   0   0   0 # Stop year, Day of year, Hour in day (0-23), Minutes (must be divisible by the model time-step)

Related Pages