Page tree

MESH - A Community Hydrology - Land Surface Model


Skip to end of metadata
Go to start of metadata

The BASINFORCINGFLAG control flag specifies the input format for driving data forcing files, as well as details about the data.

Page contents:

Configuration

Options with an equal sign (e.g., "hf=M") must be provided as a single word in the format "<option_name>=<value>" with no whitespace, such as tabs or spaces, separating the option name, equal sign, and value.

File format options

OptionDescriptionSupported Since
r2cSpecifies the input files are in r2c format.r1637
csvSpecifies the input files are in CSV format.
seqSpecifies the input files are in binary sequential (seq) format.
metSpecifies that the input file is a CLASS MET format forcing file.r1090
ncSpecifies the input files are in netCDF format.r1637

File options

OptionDescriptionSupported Since
fname=<filename>Overrides the default "basin_name" filename (without file extension).r1637
fpath=<path>Overrides the derived filename, file extension, and path. "<path>" must include the full path to the file, including file extension.
name_var=<name>Name of the variable. Only used for input files in netCDF format.
name_lat=<latitude>Name of the variable corresponding to the latitude/y dimension. Only used for input files in netCDF format.
name_lon=<longitude>Name of the variable corresponding to the longitude/x dimension. Only used for input files in netCDF format.
name_time=<time>Name of the variable corresponding to the time/t dimension. Only used for input files in netCDF format.

Time-stepping options

OptionDescriptionSupported Since
hf=<M>Frame length/file time-stepping, where "<M>" specifies the length of the frame in minutes.r1637
start_date=<YYYYMMDDHHMM>

First date of record in 4-digit year, 2-digit month, 2-digit day of month, 2-digit hour, 2-digit minutes format. Provided a partial date, the following are assumed:

  • start_date=<YYYY>: 01/01 00:00 of the specified year
  • start_date=<YYYYMM>: Day 1 00:00 in the specified month of the specified year
  • start_date=<YYYYMMDD>: 00:00 in the specified date
  • start_date=<YYYYMMDDHH>: 0 minutes of the specified hour in the specified date
time_shift=<H>Time-shift to apply to time-stamps, where "<H>" specifies the offset to apply to the start date in hours. Only supported for input files in netCDF format.

Transformation options

The transformation options are recognized but not implemented, and will have no effect for any supported input file format.
OptionDescriptionSupported Since
cm=<M>

Multiplicative factor, where:

`"data" = "(driving data input)"*M`
r1637
ca=<A>

Additive factor, where:

`"data" = "(driving data input)" + A`

Other options

OptionDescriptionSupported Since
nts=<N>The number of records "<N>" to read in to memory from file.r1637
rr_srRead extra columns for liquid precipitation and solid precipitation from the CLASS MET format forcing file. Only used for input files in the CLASS MET format.r1610
no_climDeactivate the default climate variables.r1637

Overrides

The override flags can be used alone, without any instance of "BASINFORCINGFLAG", as seen in most existing model setups and configurations. In this case, the override flags for each of the respective 7 meteorological driving variables must be listed in MESH_input_run_options.ini if running a land surface scheme. More information is provided here.

In versions of MESH prior to r1680, the override control flags do not support the file format "word" options, such as "r2c", "csv", etc.. The first option to follow the flag must be the numeric code of the input file format. See this page for the numeric options.

The word options can be used for the override control flags with any version of MESH r1680 and later.

General options set with the BASINFORCINGFLAG control flag can be overwritten for specific files and variables using the following flags:

FlagDescriptionSupported Since
BASINSHORTWAVEFLAGOverride for incoming shortwave radiation.1.2.000
BASINLONGWAVEFLAGOverride for incoming longwave radiation.
BASINRAINFLAGOverride for total precipitation rate at the surface.
BASINTEMPERATUREFLAGOverride for air temperature at the specified reference height.
BASINWINDFLAGOverride for wind speed at the specified reference height.
BASINWINDDIRFLAGOverride for wind direction at the specified reference height.r1680
BASINPRESFLAGOverride for barometric pressure at the surface.1.2.000
BASINHUMIDITYFLAGOverride for specific humidity at the specified reference height.
BASINRUNOFFFLAGOverride for runoff.r1680
BASINRECHARGEFLAGOverride for recharge.

All of the flags support this subset of the general options:

The override control flags support exactly the same options as BASINFORCINGFLAG in MESH versions r1680 and later.
OptionDescriptionSupported Since
hf=<M>Frame length/file time-stepping, where "<M>" specifies the length of the frame in minutes.r750
nts=<N>The number of records "<N>" to read in to memory from file.r833
fname=<filename>Overrides the default "basin_name" filename (without file extension).r1630

fpath=<path>

Overrides the derived filename, file extension, and path. "<path>" must include the full path to the file, including file extension.
name_var=<name>Name of the variable. Only used for input files in netCDF format.
name_lat=<latitude>Name of the variable corresponding to the latitude/y dimension. Only used for input files in netCDF format.
name_lon=<longitude>Name of the variable corresponding to the longitude/x dimension. Only used for input files in netCDF format.
name_time=<time>Name of the variable corresponding to the time/t dimension. Only used for input files in netCDF format.
cm=<M>Multiplicative factor (recognized, but not used).
ca=<A>Additive factor (recognized, but not used).
time_shift=<H>Time-shift to apply to time-stamps, where "<H>" specifies the offset to apply to the start date in hours. Only supported for input files in netCDF format.

Behaviour without BASINFORCINGFLAG

Prior to MESH version r1031, the assumed format of the forcing files is the legacy binary format (bin), for which support was removed in r846. Thus, the override control flags were required, regardless of the input file format. The assumed format of forcing files was changed to "1" (the r2c format) in r1031.

If the BASINFORCINGFLAG control flag and the variable-specific overrides are omitted, the forcing files are assumed to be in r2c format, and at a time-stepping prescribed by HOURLYFLAG (or assumed 30 minutes, if HOURLYFLAG is also omitted).

Sample uses

Example 1

In the following file, "BASINFORCINGFLAG" specifies that the forcing data are in the CLASS MET format forcing file, the first frame of data start October 1, 1994 01:00, and the frame length/time-stepping of the file is 60 minutes (hourly):

MESH_input_run_options.ini (excerpt)
##### Control flags #####
----#
    8 # Number of control flags
BASINFORCINGFLAG         met rr_sr start_date=1994100101 hf=60
SHDFILEFLAG            2
INPUTPARAMSFORMFLAG      only txt
SOILINIFLAG            0
NRSOILAYEREADFLAG      3
RUNMODE                  runsvs noroute
DIAGNOSEMODE             on
TIMESTEPFLAG           5

Example 2

In the following file, "BASINFORCINGFLAG" specifies that the forcing data are in binary sequential (seq) format, the first frame of data start January 1, 2010 00:00, and the frame length/time-stepping of the files is 60 minutes (hourly):

MESH_input_run_options.ini (excerpt)
##### Control flags #####
----#
   22 # Number of control flags
BASINFORCINGFLAG       seq start_date=2010010100 hf=60
INPUTPARAMSFORMFLAG    only txt r2c
RESERVOIRFILEFLAG      tb0
STREAMFLOWFILEFLAG     tb0
RUNMODE                runsvs runrte
SOILINIFLAG            4
INTERPOLATIONFLAG      0
NRSOILAYEREADFLAG      0
IWF                    1
BASEFLOWFLAG           2 #wf_lzs
SAVERESUMEFLAG         0
RESUMEFLAG             0
AUTOCALIBRATIONFLAG    0
PREEMPTIONFLAG         0
STREAMFLOWOUTFLAG      default
REACHOUTFLAG           daily
BASINAVGWBFILEFLAG     none
BASINAVGEBFILEFLAG     none
DIAGNOSEMODE           1
TIMESTEPFLAG          10
OUTFIELDSFLAG          0
OUTFILESFLAG           0

Example 3

In the following file, the override flags for all seven meteorological forcing variables are provided, and specify that the forcing data are in r2c format (numeric option 1), and the frame length/time-stepping of the files is 60 minutes (via HOURLYFLAG); in this case, the start date is specified in the last line of the MESH_parameters_CLASS.ini parameter file:

MESH_input_run_options.ini (excerpt)
##### Control flags #####
----#
   19 # Number of control flags
HOURLYFLAG            60
BASINRAINFLAG          1
BASINLONGWAVEFLAG      1
BASINSHORTWAVEFLAG     1
BASINTEMPERATUREFLAG   1
BASINWINDFLAG          1
BASINPRESFLAG          1
BASINHUMIDITYFLAG      1
SHDFILEFLAG            1
AUTOCALIBRATIONFLAG    1
SOILINIFLAG            1
INTERPOLATIONFLAG      0
PRINTSIMSTATUS           date_daily
RUNMODE                  runrte
OUTFILESFLAG           1
PRINTRFFR2CFILEFLAG    1
PRINTRCHR2CFILEFLAG    1
BASINAVGWBFILEFLAG       all
BASINAVGEBFILEFLAG       all

Example 4

In the following file, the override flags for all seven meteorological forcing variables are provided, and specify that the forcing data are in binary sequential (seq) format (numeric option 3), and the frame length/time-stepping of most of the files is 60 minutes (via HOURLYFLAG), with the exception that the time-stepping of the precipitation file is 360 minutes (6-hourly):

MESH_input_run_options.ini (excerpt)
##### Control flags #####
----#
   31 # Number of control flags
HOURLYFLAG            60
IDISP                  0
IZREF                  1
IPCP                   1
ITC                    2
ITCG                   2
ITG                    2
IWF                    1
IPAI                   0
IHGT                   0
IALC                   0
IALS                   0
IALG                   0
BASINRAINFLAG          3 hf=360
BASINLONGWAVEFLAG      3
BASINSHORTWAVEFLAG     3
BASINTEMPERATUREFLAG   3
BASINWINDFLAG          3
BASINPRESFLAG          3
BASINHUMIDITYFLAG      3
SHDFILEFLAG            1
FROZENSOILINFILFLAG    0
INTERPOLATIONFLAG      0
SAVERESUMEFLAG         0
RESUMEFLAG             0
OUTFIELDSFLAG          0
PRINTRFFR2CFILEFLAG    0
PRINTRCHR2CFILEFLAG    0
AUTOCALIBRATIONFLAG    1
METRICSSPINUP        366
BASEFLOWFLAG           1

Example 5

In the following file, "BASINFORCINGFLAG" specifies driving data are read from the CLASS MET format forcing file, where the "BASINRAINFLAG" and "BASINTEMPERATUREFLAG" overrides after the flag specify that precipitation and temperature data should be replaced with time-series from forcing files in the CSV format; the frame length/time-stepping of the file is specified by HOURLYFLAG:

MESH_input_run_options.ini (excerpt)
##### Control flags #####
----#
   12 # Number of control flags
HOURLYFLAG            30
BASINFORCINGFLAG         met
BASINRAINFLAG          2
BASINTEMPERATUREFLAG   2
SHDFILEFLAG            2
IWF                    0
SOILINIFLAG            0
RUNMODE                  noroute
DIAGNOSEMODE           1
BASINAVGWBFILEFLAG       daily ts
BASINAVGEBFILEFLAG       daily ts
OUTFILESFLAG           1


Example 6

In the following file, the "BASINFORCINGFLAG" is assigned to read the NetCDF (.nc) forcing files. In this example, the input forcing are GEM_CaPA data. The time-stepping (hf = 60) and start date of record is specified. 

The name of variables (name_var) should be declared appropriately based on the input forcing variable names.
MESH_input_run_options.ini (excerpt)
##### Control Flags #####                                  
33                                                     # Number of control flags                       
BASINFORCINGFLAG       nc hf=60 start_date=2004090106 
BASINSHORTWAVEFLAG     name_var=rsds
BASINHUMIDITYFLAG      name_var=hus
BASINRAINFLAG          name_var=pr
BASINPRESFLAG          name_var=ps
BASINLONGWAVEFLAG      name_var=rlds
BASINWINDFLAG          name_var=uva
BASINTEMPERATUREFLAG   name_var=ta
IDISP                  0                                #02 Vegetation Displacement Height Calculation  | A20, I4
IZREF                  1                                #03 Atmospheric Model Reference Height          | A20, I4
IPCP                   1                                #04 Rainfall-Snowfall Partition distribution    | A20, I4
ITC                    2                                #05 Canopy and Ground-Surface Temp Iter Scheme  | A20, I4
ITCG                   2                                #06 Canopy and Ground-Surface Temp Iter Scheme  | A20, I4
ITG                    2                                #07 Canopy and Ground-Surface Temp Iter Scheme  | A20, I4
IWF                    1                                #08 Water Flow control                          | A20, I4
IPAI                   0                                #09 CLASS Input Leaf-Area Index Override        | A20, I4
IHGT                   0                                #10 CLASS Input Vegetation Height Override      | A20, I4
IALC                   0                                #11 CLASS Input Canopy Albedo Override          | A20, I4
IALS                   0                                #12 CLASS Input Snow Albedo Override            | A20, I4
IALG                   0                                #13 CLASS Input Soil Albedo Override            | A20, I4
SHDFILEFLAG            1                                #21 basin shed file flag                        | A20, I4
FROZENSOILINFILFLAG    0                                #22 frozen soil infiltration flag               | A20, I4
INTERPOLATIONFLAG      1
SAVERESUMEFLAG         0								# set it 4 in case of saving  the resume 
RESUMEFLAG             0							    # set it 4 in case of reading from resume  
OUTFIELDSFLAG          0
PRINTRFFR2CFILEFLAG    0
PRINTRCHR2CFILEFLAG    0
AUTOCALIBRATIONFLAG    1
METRICSSPINUP        365
BASEFLOWFLAG           1
RUNMODE			  runrte	 	
STREAMFLOWOUTFLAG default


Related pages