MESH - A Community Hydrology - Land Surface Model


WARNING: Entries on this page are not official releases of Standalone MESH and are provided for experimental and debugging purposes. The information and features described on this or child pages may not be available in previous or in current official releases.

Users are strongly encouraged to report any issues encountered.

This page contains unofficial versions of Standalone MESH provided for experimental and debugging purposes. Packaged code on this page may include features not currently included in previous or in current official releases of MESH. This includes new sub-programs, modules, and input and output file formats and options.

The updates and features on this page will be included in the next official release of Standalone MESH.

Page sections:

Latest code and pre-compiled Windows-compatible program

Development notes

Legend: Retired release; Note; Bug identified; Bug corrected; Bug fixed; Remark

r1064

  • Added channel routing via RPN routing (i.e., RTE), an updated routing scheme based on a more recent version of Watflood, with 'RUNMODE runrte'
  • Version 2.0 of MESH_parameters_hydrology.ini must be used to parameterize RTE
  • Added the 'INPUTPARAMSFORMFLAG' control flag with the 'r2c' option to parameterize RTE by grid, using MESH_parameters.r2c
  • Changed the accumulation of daily output in the CLASSOF1, CLASSOF2, and CLASSOF3 files to account for the GRU ONLY; the accumulation no longer accounts for the fraction of the GRU in the grid (i.e., ACLASS) and grid area (i.e., FRAC) – 'OUTFIELDSFLAG' can be used for this instead 
    • For example, the accumulation of ROF in CLASSOF1 is now the sum of ROF at all time-steps from CLASSOF4
  • Changed the units of ROF in CLASSOF4 from mm s-1 to mm to match the field in CLASSOF1; prior to r1059, this field was in units of mm s-1 in CLASSOF4 and units of mm in CLASSOF1 – ROF in its diagnostic units of mm s-1 is still output at every time-step in CLASSOF7 (this remains unchanged)
  • RTE does not initialize channel storage using the first record of measured streamflow; initial channel storage is set to zero
  • Line truncation results in RTE using a power to 0.66 instead of 0.667 to calculate flow

r1087, r1088

  • Added natural reservoir routing via RTE
  • Modified reading MESH_input_reservoir.txt to use free-format; a sequence of numbers and fields must be delimited by whitespace (e.g., where the location was specified XXXX-XXXX, it must now be specified XXXX -XXXX)
  • Added the 'STREAMFLOWFILEFLAG' and 'RESERVOIRFILEFLAG' control flags with the 'tb0' option to support tb0 format input files (e.g., MESH_input_streamflow.tb0 and MESH_input_reservoir.tb0); the flags can be omitted or the 'txt' option can be used to revert to using the text format files
  • Depreciated 'LOCATIONFLAG'; either integer or real location points can be specified in MESH_input_streamflow.txt or MESH_input_reservoir.txt; both are read as free-format – the location in the text format files is still read in units of minutes (this remains unchanged)
  • Controlled reservoirs (i.e., streamflow insertion) is not currently supported via RTE
  • r1087 introduces an error when RTE saves streamflow; the simulated values are near zero 

r1089

  • Added controlled reservoir routing/streamflow insertion via RTE; the model will stop if it runs out of release data, or if any initial release value is zero
  • Added the ability to skip records in MESH_input_reservoir.tb0, relative to the starting date of the release data
  • r1087 introduces an error when RTE saves streamflow; the simulated values are near zero (this issue persists)
  • RTE does not initialize reservoirs using the area or initial level of the reservoir specified in MESH_input_reservoir.tb0
  • RTE does not allow streamflow insertion from MESH_input_streamflow.tb0 or MESH_input_streamflow.txt – requires user hard-coded changes

r1105

  • Fixed a bug when RTE saves daily streamflow that was causing near zero flow, introduced in r1087
  • Fixed a bug related to defining routing parameters in both MESH_parameter_hydrology.ini (2.0) and MESH_parameters.r2c for RTE, and fixed a bug when parsing multi-word attribute names in MESH_parameters.r2c that omitted the 'level' identifier; both introduced in r1087
  • Fixed a bug that mixed ':Coeff6' and ':Coeff7' in MESH_input_reservoir.tb0, which assigned reservoir area and zero level to the wrong variables, introduced in r1087
  • Added option '2' for 'SHDFILEFLAG', which can be combined with the 'BASINFORCINGFLAG' control flag with option 'met', to run in a point mode using the CLASS format MET file (renamed 'basin_forcing.met') and MESH_parameters_CLASS.ini
  • Added checks for bad 'iy' and 'jx' values (e.g., x and y grid location of RANK), to help identify if ':TotalNumOfGrids' is bad in MESH_drainage_database.r2c
  • Added support for 'level' identifiers when reading attributes names from MESH_parameters.r2c; canopy parameters should include the canopy type after the variable name, e.g.,: fcan /[nl, bl, cr, gr, ur]; soil parameters can include the layer number after the variable name, e.g.: sand /[1, 2, 3, ...n] – for soil parameters, if no 'level' is provided then the value is assigned to all layers (i.e., to the entire profile)
  • Updated BASEFLOWFLAG
    • Added BASEFLOWFLAG option '1' for SVS; replaced option '2' with a grid-based scheme adopted from RTE (and documented in the Watflood manual); removed the in-line baseflow from RTE – BASEFLOWFLAG should be activated with option '2' or 'wf_lzs' instead
    • Replaced the 'WF_LZFA' and 'WF_LZFPWR' parameters with flz and pwr; these parameters can be defined by number of river classes (e.g., max of IAK in MESH_drainage_database.r2c) in MESH_parameters_hydrology.ini (2.0) or by grid in MESH_parameters.r2c with 'INPUTPARAMSFORMFLAG r2c'
    • Added word options to configure BASEFLOWFLAG in MESH_input_run_options.ini, though the numeric options are still supported – the equivalent word options will print to MESH_output_echo_print.txt when BASEFLOWFLAG is active
    • Behaviour and parameterization of 'BASEFLOWFLAG 1' remains unchanged when running CLASS 3.6
  • Added lower zone and deep zone storage ('LZS', 'DZS')
    • Added storage held in the lower zone ('LZS') and deep zone ('DZS') to the storage printed in MESH_output_echo_print.txt and to all Basin_water_balance*.csv files, and to the screen – only BASEFLOWFLAG contributes to 'LZS', and no modules or processes currently contribute to 'DZS'
    • Inserted two columns to all Basin_water_balance*.csv files for 'LZS' and 'DZS', which print before the 'STG' and 'DSTG' columns
  • Updated how grid and basin area are accumulated for basin totals, which can cause minor rounding differences in accumulated variables (e.g., variables with the ACC suffix and daily streamflow) – this is particularly evident in large basins

r1130

  • Updated RTE to write the daily average streamflow value (in place of the instantaneous end-of-day value) to MESH_output_streamflow.csv
  • Added the 'wf_route' option flag to MESH_parameters_hydrology.ini (2.0) with the 'rl_shd' option to override the assumed channel length with the 'ChnlLength' attribute from MESH_drainage_database.r2c, and the 'cap_shd' option to override the channel capacity calculation with the 'Bankfull' attribute from MESH_drainage_database.r2c
  • Added the 'rte' option flag to MESH_parameters_hydrology.ini (2.0) with the 'cap_shd' option to override the assumed channel capacity calculation with the 'Bankfull' attribute from MESH_drainage_database.r2c
    • RTE already uses the 'ChnlLength' attribute from MESH_drainage_database.r2c, so the 'rte' option flag has no 'rl_shd' option 
  • Added support for distributed IWF
    • Supported by grid by adding an attribute named 'iwf' in MESH_parameters.r2c (requires the 'INPUTPARAMSFORMFLAG' control flag with the 'r2c' option)
    • Supported by GRU as a GRU-dependent parameter named 'iwf' in MESH_parameters_hydrology.ini (2.0)
    • Changes to the structures of WATROF, LATFLOW, and WATDRN may cause minor rounding differences to ROFS (i.e., interflow), and thus to ROF and streamflow

r1149 (exe)

  • Fixed a bug when reading reservoir release values from file if the number of 'controlled' reservoirs is less than the total number of reservoirs in the file
  • Fixed a bug where a check of NA and NAA disables point mode (e.g., 'SHDFILEFLAG 2')

r1209

  • Restored the energy balance file and added options for daily, hourly, monthly, or per time-step (ts) output; the output frequency is configured by the 'BASINAVGEBFILEFLAG' control flag (using the same frequency options supported by the 'BASINAVGWBFILEFLAG' control flag); the default output frequency is 'daily' 
    • Most diagnostic outputs from SVS are missing
    • The 'BASINAVGEBFILEFLAG' control flag does not support the extended options of the 'BASINAVGWBFILEFLAG' control flag
  • Added support for reading 'ORGM' from MESH_parameters.r2c (requires the 'INPUTPARAMSFORMFLAG' control flag with the 'r2c' option)
  • Added support to run SVS in parallel
  • Updated reservoir code in WF_ROUTE to store accumulated inflows in a more appropriate variable; inflows from the reach output should be read from the 'QISIM' instead of 'QISIM0' column; a future update will remove the diagnostic 'REACH', 'RANK', 'QISIM0', and 'STGCH0' columns from the file
  • MPI runs on Cygwin using a higher 'np' value will result in corrupted MPI exchange after a certain number of time-steps into the run; this seems to be a limitation in the OpenMPI implementation in Cygwin, and the same does not occur on Linux, Linux subsystem for Windows, or clusters with either Intel or GCC OpenMPI distributions

r1221

  • Added initialization of channel storage to RTE (missing since r1064)
  • Fixed the Cygwin MPI issue introduced in r1209
  • Fixed the truncation of the power used in RTE to calculate both overbank and in channel flow (from 0.66, corrected to 0.667), introduced in r1064
  • Added daily output for reservoir inflow, storage, and outflow; for WF_ROUTE, storage is assigned a 'NODATA' value because reservoir "storage" is not a volumetric capacity
    • The diagnostic 'REACH', 'RANK', 'QISIM0', and 'STGCH0' columns have been removed from the file
  • Added daily output of lake level; output of this file cannot be disabled if reservoirs are present
  • Changed how 'CMAS' is aggregated for the energy balance file to only consider canopies that contain vegetation when aggregating the value from tile

r1231

  • Added resume files for RTE and SVS
  • Added special condition: GRUs with mosaic ID >= 100 are not assigned grid-based values if MESH_parameters.r2c is used

r1350

  • Fixed a time-stepping issue with how ALBT is calculated for outputs
  • Fixed an issue in RTE when initializing reservoir storage using the polynomial coefficients
  • Added internal routines to aggregate and accumulate output variables
  • Added the 'next' group in the internal date counter to more easily identify the end of a period (for developers)
  • Fixed a bug with the way seasonal outputs are calculated
  • Added a fix for the way arrays are dynamically dimensioned to improve compatibility with older compilers (tested with GCC 4.4.7)
  • Fixed a bug related to a lookup table used to identify the last day of month – not used in TRUNK but used in some development branches
  • Added common print routines to handle outputs to screen and MESH_output_echo_print.txt (for developers)
    • Messages printed to screen are also now copied to MESH_output_echo_print.txt 
  • Replaced the old makefiles with one makefile that accepts targets – compilation instructions have changed
  • Removed the 'Julian_Day_ID' routine; new routines in 'module_dates', like 'jday_to_tsteps', 'get_jdate', and 'get_jday', should be used instead (for developers)
  • Fixed bugs with flags read from MESH_input_run_options.ini that have been updated to allow options and keywords, where the former binary options were not properly handled
  • Added additional safety checks for missing and/or invalid values in the basin configuration
  • Added the 'ensim_io' module to handle reading EnSim (Green Kenue) format files; the new routines are more flexible and resilient than in the old code, and allow many of the former read routines to be consolidated (for developers)
  • Added the 'map' option to 'SHDFILEFLAG' to print a Watflood Map file based on MESH_drainage_database.r2c
  • Fixed a time-stepping bug with reading reservoir release from file
  • Added additional diagnostic information to the summary of streamflow gauge locations and reservoir outlets printed with 'DIAGNOSEMODE' enabled
  • CLASS 3.6
    • Fixed a bug where the user-specified LSS time-step override via 'TIMESTEPFLAG' did not update the CLASS time-step; the issue did not impact SVS
    • Fixed a bug where the THFC override in CLASSB was not assigned to the correct layer if SDEP did not fall inside the last layer in the profile; the issue did not impact SVS
    • Fixed a bug when non-permeable soil status should be assigned to deep soil layers, when no layer in the soil was identified by GRU as non-permeable in MESH_parameters_CLASS.ini but assigned a non-permeable soil texture in MESH_parameters.r2c
  • Significant updates were made to 'OUTFIELDSFLAG'
    • Outputs are no longer multiplied by FRAC by default – this can be reverted by adding the 'apply_frac' option to the entry in outputs_balance.txt
    • Files are created in the general output folder specified in MESH_input_run_options.ini – the output folder and number of entries specified in outputs_balance.txt are no longer used; entries can be disabled by commenting the line with '!' or '#'
    • Added tile-based outputs with the 'tsk' option
    • Added the ability to filter grid-based outputs by GRU, with the 'gru' option

r1398 (exe)

  • Updated routines for permafrost outputs (via OUTFIELDSFLAG)
  • Fixed an error where storage terms are accumulated but not averaged for outputs
  • Added the 'gru_include' and 'gru_exclude' options for OUTFIELDSFLAG
  • Changed SIMSTATS to create outputs in the general output folder specified in MESH_input_run_options.ini – scripts used to run MESH should be updated to accommodate this change
  • Fixed a bug in the flow initialization routine of RTE that could cause initialized channels to re-initialize
  • Added a warning when DA is zero at a streamflow gauge location
  • Added extra checks in the flow initialization routine in RTE to prevent a crash when DA at a streamflow gauge is zero
  • Changed the code to write the streamflow gauge and reservoir outlet location summaries to MESH_output_echo_print.txt, regardless of the state of 'DIAGNOSEMODE'
  • Improved many of the error, warning, and diagnostic messages
  • Added the 'PRINTSIMSTATUS' control flag to control how frequently simulation status is printed to the screen
  • Added the 'program_end' and 'program_abort' routines (for developers)
  • Improved the information provided by error, warning, remark, and diagnostic messages throughout the code

r1421

  • Removed unused 'LOCATIONFLAG' and 'VARIABLEFILESFLAG' control flags; added 'OUTFILESFLAG' to replace 'OUTFIELDSFLAG', though using 'OUTFIELDSFLAG' is still supported
  • Added additional output variables and re-activated outputs of 'STGW' (formerly: 'STG') and 'DSTGW' (formerly: 'DSTG')
  • Added global routine for updating and managing internal output variables, as well as global output variable structure (for developers)
  • Fixed a bug introduced in r1381 where a wrong path is used to check for the existence of the MonteCarlo.txt file (to correctly append to the file when the file exists)
  • Added outputs for PDMROF 'FSTR' variable
  • Renamed the internal variable structure from 'stas' to 'vs' (for developers)
  • Added additional checks when compiling the 'debug' option for the GCC gfortran compiler

r1461

  • This release was omitted from general distribution because of performance degradation related to new 'MESH level' global output variables; this issue is resolved by updates in r1555 and later
  • Added global 'basin averaged' variables for model variables and for outputs, automatically calculated at the 'MESH' level (for developers)
  • Fixed errors in the global outputs with calculating time-averaged variables when dealing with partial coverage and/or activity (e.g., TCAN, CMAS, TSNO, TPND)

r1593 (exe)

  • Fixed an issue where the 'best' value could be overwritten in the function_out.txt file when 'PREEMPTIONFLAG' is enabled
  • Restored the ability to read multiple blocks of driving data into memory using the 'nts' option
    • Testing shows enabling this feature no longer results in a significant performance gain as performance has already been substantially improved by other recent updates in the framework
  • Fixed an issue introduced by updates in r1087 where the scenario of the simulation start date being before the start date of the streamflow input file creates a 'WARNING' message instead of an 'ERROR' to stop the program
  • Fixed a bug where soil texture read from other file formats could be replaced with values read from MESH_parameters_CLASS.ini
  • Added the 'NUDGESDEPFLAG' control flag with option '1' to nudge SDEP to the nearest interface between layers (defined by MESH_input_soil_levels.txt) to ensure a hydraulically active lens is not added to the bottom of the soil profile that underlies thicker layers at depth (to avoid numerical instabilities)
  • Added the Kling-Gupta efficiency (KGE) coefficient to the list of metrics printed to Metrics_Out.txt
  • Updates to CLASS 3.6:
    • Restored the option to let SAND equal zero in CLASS (CLASSB/CLASSBG)
    • Added the option to apply 'FCAN' and 'LNZ0' to all canopy types when no specific canopy type is specified in the attribute name when reading from MESH_parameters.r2c
    • Fixed a performance bug when initializing the 'QAC' variable
  • Added initial code for the 'MESH_initial_values.r2c' file; until this feature is fully implemented, it is not recommended to have a file named 'MESH_initial_values.r2c' inside the main MESH folder
  • Updates to SVS 1:
    • Updated to branch version "svs_GEM_v5.8.rc2" r720 (testing and further alignment between MESH and the SPS driver is ongoing)
    • Fixed assigning the wrong MESH variable (soil thickness instead of soil depth) to the SVS 'dl_svs' variable
    • Added minimum allowed values for topographic slope (0.005) and for rooting depth (0.5 m) for SVS
  • Added a new diagnostic message to better inform parameter selection (e.g., for calibration) when a GRU definition exists but the GRU is not active in any cell inside the domain
  • Added outputs for snow-related variables, including 'FSNO', 'ZSNO' and 'RHOSNO', and for the precipitation partitioning components (see notes here, and the updated variable list here)
    • Labelled 'ROF', 'ROFSNO' may not necessarily contribute to 'ROFO' (e.g., if instead it infiltrates into the soil); see notes here
  • Fixed a bug introduced in r1461 where the component of 'SNO' was erroneously omitted from the calculation of total storage 'STGW'
  • Updates to RTE 1:
    • Fixed a bug when initializing 'qi' inflow in 'flowinit', added allowances for when 'NA' is equal to 'NAA' in improperly configured basins
    • Restored the use of the monthly-based lookup tables for the legacy domain-specific reservoir operations hard-coded in RTE
    • Added resuming 'lake_elv' to properly restore storage for the inline reservoir operations based on level (this change is compatible with all existing 'rte' resume files)
  • Restored "point-mode" activated by the 'SHDFILEFLAG' control flag with option '2'
    • Changed the logic to allow grid-based processes, such that outputs can be created via 'OUTFILESFLAG'
    • Fixed how driving data are read from the 'basin_forcing.met' file, and it should be possible to read driving fields from other file formats (e.g., to replace the values read from 'basin_forcing.met') so long as 'BASINFORCINGFLAG met' preceeds the respective 'BASIN*FLAG' inside the list of control flags in MESH_input_run_options.ini

Compiling the code

Releases of Standalone MESH r1298 and later include one generic makefile that merges the capabilities and compile options of the individual makefiles that were included with prior versions. Consequently, the process to compile the code is revised.

Compiling at the command prompt

The makefile interprets targets to enable compiler options when compiling the code. The general structure of the make command is: make [target]

The file "-f" option is no longer used.

To compile the code:

  • 'cd' to the appropriate folder
  • Choose an appropriate option:
    • To compile the serial code using GCC compiler, run: make
    • To compile the serial code using Intel compiler, run: make ifort
    • To compile MPI-capable code using GCC compiler, run: make mpi_gcc
    • To compile MPI-capable code using Intel compiler, run: make mpi_intel
    • To compile the distributable (i.e., static) serial Windows-compatible code using MinGW-w64 compiler, run: make mingw_static

All targets are CaSe-SeNsItIvE. The following commands will NOT work: make MPI_GCC; make mpi_GCC; make mpi_Intel; etc..

README.txt is a new file included alongside the makefile. It includes additional examples and describes the targets in more detail. It also documents the internal variables of the makefile. To override the default options of the targets, omit the target and assign the correct options to these variables directly in the make command, e.g.: "make MPI=ompi DEBUG=yes" is equivalent to "make mpi_gcc debug".

As with the targets, the options supported by the internal variables are CaSe-SeNsItIvE.

By default, the new make routines will automatically delete intermediate compilation files, such as the *.o and *.mod files. To preserve these, add the "debug" target.

The "debug" target will disable code optimization and enable additional compilation options for debugging code. The "debug" target should not be used when compiling optimized code for running analyses. The "debug" target should always be used when developing and testing new code.

To compile the code using the "debug" option:

  • 'cd' to the appropriate folder
  • Choose an appropriate option:
    • To compile the serial code using GCC compiler, run: make debug
    • To compile the serial code using Intel compiler, run: make ifort debug
    • To compile MPI-capable code using GCC compiler, run: make mpi_gcc debug
    • To compile MPI-capable code using Intel compiler, run: make mpi_intel debug

New and revised features and options

Sub-programs and modules

SVS (land surface scheme)

RTE (stream channel routing, reservoir routing)

Run options

RUNMODE
Control flag to describe the active land surface scheme and routing routine.

INPUTPARAMSFORMFLAG

STREAMFLOWFILEFLAG

RESERVOIRFILEFLAG

BASEFLOWFLAG
Control flag to activate a module that maintains lower zone storage and calculates baseflow.

OUTFIELDSFLAG (updated)

PRINTSIMSTATUS (formerly VERBOSEMODE)

Input and output files

MESH_input_reservoir.txt (free format)

MESH_parameters_hydrology.ini (2.0)
Version 2.0 of MESH_parameters_hydrology.ini introduces several enhancements and improvements over older formats of the file.

MESH_parameters.r2c

MESH_input_streamflow.tb0
MESH_input_streamflow.tb0 is an EnSim/Green Kenue table file used by WATFLOOD that contains streamflow gauge metadata, location, and flow data.

MESH_input_reservoir.tb0
MESH_input_reservoir.tb0 is a WATFLOOD-compatible, EnSim/Green Kenue table file that contains reservoir outlet metadata, location, and optionally release data.