MESH - A Community Hydrology - Land Surface Model

Program and Source

A new version of Standalone MESH is available, SA_MESH_1.4.1037.

The program and source code may be updated if critical bugs have been found and are fixed. The version written to screen by the program may still show "1022". If possible, sign in to the Wiki and 'watch' this page to receive an email when this content is updated.

Page contents:

Known Issues

This issue has been corrected in the most recent program and source file links (SA_MESH_1.4.1022_source_latest.zip and SA_MESH_1.4.1022_exe_latest.zip).

The LQWS, FRWS, and ALWS fields for individual soil layers are printed to the water balance files in CSV format in an order that does not match the order of the fields in the file header. The order of these fields in the header is (('LQWS', 'FRWS', 'ALWS'), j = 1, NSL), whereas the order of the values printed is ((LQWS, j = 1, NSL), (FRWS, j = 1, NSL), (ALWS, j = 1, NSL)). A bug-fix in r1024 corrects this, which prints these fields in the same order as in the file header. The values of these fields are unaffected by this bug.

The fields for total LQWS, FRWS, and ALWS (of the entire soil profile, and which contain no integer label in the header), STG, and DSTG are correctly labelled and unaffected by this bug.

General Updates

Bug-fixes to the WF_ROUTE inline routing and time-stepping

These errors in the inline routing (WF_ROUTE) and in the simulation time-stepping have been fixed in the MESH 1.4 series of code. In some setups, these fixes may create different simulated streamflow, in particular during flooding and peak flow events, when MESH 1.4 is run using routing parameters from MESH 1.3 setups (MESH 1.3.003 and later). The runoff generated by CLASS remains unchanged.

  • In previous versions of MESH, the simulation day was incremented before calling WF_ROUTE. As a results, the output of precipitation, evaporation, and runoff at each day to the screen was offset by a day, relative to the observed and simulated streamflow values.
  • In all prior versions of MESH, an incorrect type set of the "a" coefficients in WF_ROUTE caused channel capacity to be determined using rounded values, which may derive slightly different channel geometry than by the MESH 1.4 series of code. To emulate the previous behavior, the coefficients can be manually provided with the WF_A1, WF_A2, WF_A3, and WF_A4 parameters using version 2.0 and higher of the MESH_parameters_hydrology.ini input file.
  • In MESH 1.3.003 and all later versions of MESH 1.3, an incorrect coefficient is determined for the roughness coefficient of the floodplain R1, resulting in the derived value R1=2.0*WF_R2*WF_R2, instead of R1=2.0*WF_R2 as intended. The MESH 1.4 series of code may generate different streamflow outputs and metrics based on them, especially around flooding and peak flow events, when driven using MESH 1.3 parameter files (the runoff generated by CLASS remains unchanged).

Performance improvements

  • Continued optimization and clean-up of the code have improved the general run time of MESH by up to 20% and reduced memory usage by over 50%. MESH 1.4 also supports the MPI (message passing interface) protocol for parallelized runs (details here), which can further improve run time by over 80%, depending on the number of grid cells and GRUs in the setup and the number of parallel cores and processors used.
  • New control flags have been introduced to minimize write operations to disk, to further improve the general run time of MESH. Further, only the daily basin-average, daily streamflow, and diagnostic output files are now written by default (the other outputs can be optionally activated with control flags in the MESH_input_run_options.ini input file).

Added interflow algorithm (LATFLOW)

  • MESH 1.4 introduces LATFLOW (activated with option 3 on the IWF control flag), which combines the PDMROF (overland ponding model) and WATROF (sloped overland and interflow) algorithms. Additionally, PDMROF, WATROF, and "flat-CLASS" can still be run with IWF options 2, 1, and 0, respectively.

Updates for Existing Setups

File formatting 

All input files, with the exception of MESH_input_reservoir.txt are now read in free format. All fields in a single line should be separated by one or more spaces. The length and precision of the fields is no longer fixed.
MESH_input_reservoir.txt still requires strict formatting.

Components of the streamflow gauge location must now be separated by one or more spaces in MESH_input_streamflow.txt.

Previously:

 2940-5185  02BA003 2970-5185

Now required:

2940 -5185  02BA003 2970-5185

Values must now be separated by one or more spaces in MESH_parameters_CLASS.ini.

Previously:

   0.083   0.362   0.4680.30E-02       1 !> 13XSLP/GRKF/MANN/WFCI/MID

Now required (option 1: reformatting the number to reduce the number of required spaces):

   0.083   0.362   0.468   0.003       1 !> 13XSLP/GRKF/MANN/WFCI/MID

Now required (option 2: adding a space, since fixed-formatting is no longer required):

   0.083   0.362   0.468 0.30E-02       1 !> 13XSLP/GRKF/MANN/WFCI/MID
The MESH_output_streamflow.csv output file now includes a header by default. This can be disabled using the 'no_header' option on STREAMFLOWOUTFLAG (e.g., STREAMFLOWOUTFLAG daily no_header). However, an extra column (YEAR) is now included in the file, regardless. Post-processing scripts should be updated as necessary.
The Basin_average_water_balance.csv output file now includes a "delta storage" term to complete the water balance. The "delta storage" term for the accumulated fields (i.e., the run totals) now immediately follows the columns for other accumulated variables. Post-processing scripts should be updated as necessary.
The YEAR and DAY columns in most CSV output files have been re-ordered. The YEAR column now precedes the DAY column. Additionally, if the output file supports output at other time intervals, the default order of the time-step columns is now YEAR, DAY, HOUR, MINS, where MINS is the 00 or 30 interval of the hour.

Input forcing file time-stepping

Input forcing files are no longer required to use the same time-stepping. The HOURLYFLAG option should be set before all BASIN*FLAG's; however, the 'hf=' option on any BASIN*FLAG can be used to override the HOURLYFLAG value. If HOURLYFLAG is not defined, the default stepping is half-hourly (e.g., HOURLYFLAG 30). More information on the meteorological forcing files here.

The built-in interpolation option by INTERPOLATIONFLAG 1 uses arithmetic averaging and is not recommended for the interpolation of precipitation rate for durations greater than HOURLYFLAG 60.

Updated Output control flags

A number of new control flags can be added to MESH_input_run_options.ini to enable or disable saving certain output files at various time intervals.

Revision History

December 14, 2016

General Updates

  • Removed the STREAMFLOWFLAG control flag (replaced with option "ts" on the STREAMFLOWOUTFLAG control flag instead)
  • Added the REACHOUTFLAG control flag (only supporting the 'ts' option)
  • Added the RUNMODE control flag
  • Added an experimental version of the Soil-Vegetation-Snow (SVS) land surface scheme (as an alternate to CLASS); more details on SVS here
  • Added the CROPLANDIRRIGATION control flag to calculate irrigation demand based on PEVP
  • Changed the behavior to continue running (printing 'NO_DATA' values for observations) when no more records for streamflow exist in MESH_input_streamflow.txt
  • Added options 4 and 5 for SAVERESUMEFLAG and RESUMEFLAG (details here)
  • Removed support for options 1 and 2 of SAVERESUMEFLAG and RESUMEFLAG (no longer possible with MPI implementation and with removing the CLASSG and CLASSS routines from inside the model loop in MESH 1.3.733)
  • Reduced the memory required for simulations by optimization of internal variables
  • Fixed where the longitudinal component of reservoir outlet locations was incorrectly derived with LOCATIONFLAG (added with the addition of the LOCATIONFLAG control flag in MESH 1.3.647)
  • Added the DIAGNOSEMODE control flag to print extra configuration, diagnostic, and debug information to the MESH_output_echo_print.txt output file and to screen
  • Removed certain instances of Fortran 2003 polymorphism of routines inside data types to revert compatibility with older versions of open-source compilers (GCC/gfortran 4.3)
  • Removed the TESTCSVFLAG control flag (no longer supported)
  • Removed hard-coded paths from makefile.def ('make' will look inside the current folder and subfolders within it by default)
  • Added MPI parallelization for distributing calculations across multiple cores and processors (more details on running in parallel using MPI here)
  • Removed the fixed-formatting requirement for reading control flags in MESH_input_run_options.ini
  • Fixed the code to no longer create the "nul" output file (which was then difficult to delete on Windows machines using Explorer)
  • Added the NRSOILAYEREADFLAG control flag to read soil parameters and initial values from MESH_parameters_CLASS.ini for more than 3 soil layers
  • Updated the release to "1.4" and version to "1022"

Climate Forcing Files

  • Added the climate_info.ini input file to perturb forcing fields by weights specified by GRU (automatically activated if present)
  • Removed support for the old binary format forcing file (MESH_forcing.bin using "file format" option 0); more details on meteorological forcing files here
  • Removed the experimental 'alpharain' option
  • Added the "nts=" option for BASIN*FLAG control flags to read multiple frames of data into memory at a time (replacing "file format" option 5)
  • Added the "hf=" option for the BASIN*FLAG control flags (specified in MESH_input_run_options.ini) to override the default frame length specified via HOURLYFLAG (more details on meteorological forcing files here)

Inputs and Outputs (general)

  • Changed the spacing of columns for several output files
  • Added the BASINAVGEVPFILEFLAG control flag and Basin_average_evap.csv output file for evapotranspiration related terms
  • Added the "none", "daily", "ts", "hourly", "monthly", and "all" options for the BASINAVGWBFILEFLAG control flag (the default option remains only to print the daily file)
  • Added the BASINAVGEBFILEFLAG control flag
  • Re-ordered columns in the Basin_average_water_balance.csv and Basin_average_energy_balance.csv output files
  • Added the 2.0 version of the MESH_parameters_hydrology.ini input file
  • Added the BASEFLOWFLAG control flag for simple lower aquifer representation

Gridded Outputs (OUTFIELDSFLAG)

  • Removed aerial-averaging of outputs to more appropriately represent gridded point outputs (the behavior can be restored with the "apply_frac" option
  • Restored support for outputs of LQWS (accidentally removed when support was added for THLQ and THIC in MESH 1.3.733)
  • Fixed an indexing issue when printing QEVP at the daily interval
  • Added the "txt" and "csv" output options, and "printdate" options
  • Added the "printdate" (for txt or CSV output), "gridorder", and "shedorder" options

CLASS

  • Added option 3 to the IWF control flag to activate LATFLOW
  • Fixed printing the FC, FCS, FG, and FGS values to the CLASS point output files to use the grid index instead of the tile index (to be consistent with the index used to print other fields in those files)

Inline routing (WF_ROUTE)

  • Restored WF_R1=2.0 (a "fix" made in MESH 1.3.003, where the purpose and use of WF_R1 was misunderstood and caused the derived roughness coefficient for the floodplain to be R1=2.0*WF_R2*WF_R2, instead of R1=2.0*WF_R2 as intended); streamflow outputs and metrics based on them may differ, especially around flooding and peak flow events, when MESH 1.3 parameter files are used with the MESH 1.4 series of code (the runoff generated by CLASS remains unchanged)
  • Added the ability to read in the WF_A1, WF_A2, WF_A3, and WF_A4 coefficients to override the previous values hard-coded in WF_ROUTE, which are used to derive channel geometry (requires version 2.0 and higher of the MESH_parameters_hydrology.ini input file to provide these inputs; the old values are assumed if explicitly parameterization is not provided)
  • Fixed an index error when the no storage/no flow error is triggered
  • Fixed mixed indexing when initializing controlled reservoirs
  • Added missing components of local inflows when accumulating flows contributing to a reservoir for modelled reservoir release
  • Fixed incorrect data type setting of the 'a' coefficients in WF_ROUTE, which are used to derive channel geometry (to emulate the previous behavior, manually provide the rounded coefficients as WF_A1, WF_A2, WF_A3, and WF_A4 parameters using version 2.0 or higher of the MESH_parameters_hydrology.ini input file)
  • Fixed a bug where the last time-step in the simulation day was incremented before calling WF_ROUTE; streamflow outputs and metrics based on them may differ when MESH 1.3 parameter files are used with the MESH 1.4 series code (the runoff generated by CLASS remains unchanged)

Standalone WATROUTE (RPN_watroute)

  • Updated the RPN_watroute code
  • Fixed incorrect aerial-averaging in the runoff and recharge outputs for standalone WATROUTE

SIMSTATS (AUTOCALIBRATIONFLAG)

  • Modified the formatting of the output files created by SIMSTATS (AUTOCALIBRATIONFLAG)
  • Added columns for Gauge (ID), AbsBIAS, NegNSD, and NeglnNSD in the Metrics_Out.txt output file