MESH - A Community Hydrology - Land Surface Model

Page contents:

Program and Source

This version is succeeded by a more recent version of MESH.
This version of MESH has new instructions for compilation.

Known Issues

MESH 1.4.1398 cannot be used to run in "point mode".
Aggregated and accumulated outputs, such as those in the "ACC" columns of the Basin_average_water_balance.csv output file and the end of run totals ("final tally") are no longer preserved with option 4 of SAVERESUMEFLAG and RESUMEFLAG.

General Updates

Compiling

This version of MESH has new instructions for compilation.

MESH 1.4.1398 introduces a new makefile to simplify the compilation process. Targets are specified with the "make" command to customize the compilation process. The general structure of the make command is: make [target]

The command "make -f [filename]" is no longer supported.

To compile the code:

  • 'cd' to the appropriate folder
  • Choose an appropriate option:
    • To compile the serial code using the GCC/gfortran compiler, run: make
    • To compile the serial code using Intel ifort 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/gfortran 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 for development or debugging purposes, add the "debug" target to the end of the regular compilation command.

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/gfortran compiler, run: make debug
    • To compile the serial code using Intel ifort 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
    • To compile MPI-capable code using Intel compiler and working with NetCDF forcing files, run: make mpi_intel netcdf debug

Basin-average output files

MESH 1.4.1398 removes the HFS and QEVP columns previously available in the Basin_average_energy_balance.csv file and replaces them with the FSIN, FSOUT, ALBT, FLIN, FLOUT, GTE, QH, QE, GZERO, TA, TCAN, CMAS, TSNOW, TPOND, and TBAR (one column for every soil layer, labelled with the soil layer) columns.

The behavior has also restored to print the daily Basin_average_energy_balance.csv output file by default. The file can be disabled by configuring the BASINAVGEBFILEFLAG control flag, which now supports the "daily", "monthly", "hourly", "ts", "none", and "all" options.

Gridded outputs (OUTFIELDSFLAG)

MESH 1.4.1398 adds global output variables to ensure consistency in outputs across various outputs files and formats.

The capabilities and options available using OUTFIELDSFLAG (configured with outputs_balance.txt) have also been greatly enhanced. General options are no longer variable-specific, and all of the general options can be used to configure outputs for any of the accessible global output variables. The list of output variables available for output using OUTFIELDSFLAG is here.

Existing outputs_balance.txt files can be used with MESH 1.4.1398, but certain lines no longer have any effect:

  • The output path, previously specified in the first line of the file, no longer has any effect; outputs will be created in the output folder specified in MESH_input_run_options.ini
  • The number of variables in the file, previously specified in the second line of the file, no longer has any effect; the whole file is scanned for valid output variable entries

Specific entries in the file can be disabled by commenting the relevant line with a leading '!' or '#'.

Migrating to MESH 1.4

MESH 1.4.1398 requires the same formatting changes as MESH 1.4.1022 and MESH 1.4.1149 when migrating older setups. No changes are required to migrate from MESH 1.4.1149.

In the migration of CLASS to version 3.6 in MESH 1.3.009, the THFC formulation based on Soulis (2009) was incorrectly assigned to the bottom-most layer in mineral soils, instead of to the deepest permeable layer in the soil column. This change was corrected in revision 1336 and impacts all releases of MESH 1.3 from version 1.3.009 and later, and all releases of MESH 1.4 until this version. MESH 1.4.1398 fixes this issue.

There is no impact to previous versions that ran using setups where SDEP occurs inside or below the total depth of the column (ZBOT(NSL)), in which case the deepest permeable layer and the bottom-most layer are the same layer inside the soil column.

Outputs generated by SIMSTATS (AUTOCALIBRATIONFLAG) are now written to the general output folder specified in MESH_input_run_options.ini, and no longer in the base directory that contains the MESH input, forcing, and parameter files. Scripts must be updated to point to the new location.
Outputs generated using OUTFIELDSFLAG are now written to the general output folder specified in MESH_input_run_options.ini, and no longer in the location specified in outputs_balance.txt. Scripts must be updated to point to the new location.

Revision History

May 11, 2018

General Updates

  • Added the PRINTSIMSTATUS control flag with the options "on" (or 1), "off" (or 0), "monthly", "date_daily", and "date_monthly" to control the date format (YEAR JDAY or YEAR/MONTH/DAY) and frequency (daily or monthly) of the summary output printed to screen during the simulation, or to disable the summary output completely during the simulation (the default behavior remains the "YEAR JDAY" format and daily frequency)
  • Added a warning if the drainage area (derived from the drainage database) is zero when identifying streamflow gauge locations from the streamflow input file
  • Added a warning if the first flow value (after skipping records) is zero when positioning to the current record in the streamflow input file (in which case, channels should be initialized to zero by the respective routing scheme)
  • Reversed the order of RANK and drainage area DA printed in the summary of streamflow gauge locations, and removed the condition for DIAGNOSEMODE to be enabled (so the summary is always printed to the diagnostic output file)
  • Added support for meaningful labels for structures, like streamflow gauge and reservoir outlet locations, with the intent to improve labels in outputs (not used)
  • Added support to derive the theoretical area for lakes and reservoirs (defined as "reaches") using areas from the drainage database where not provided by the reservoir input file (the full grid area is considered in the derivation, there is no consideration for sub-grid fractions, such as masking by water tile or specific GRUs)
  • Added AREA in the summary of reservoir outlet locations, and removed the condition for DIAGNOSEMODE to be enabled (so the summary is always printed to the diagnostic output file)
  • Split the summary of reservoir output locations into separate lists by reservoir type to more easily distinguish between reservoirs using routing (those which require parameterization) versus those using insertion (those which require a time-series of input flows)
  • Added word options to the SHDFILEFLAG control flag
  • Added the "to_map" option to SHDFILEFLAG to create a WATFLOOD map file from MESH_drainage_database.r2c (this feature may not work for drainage database files created by bsn.exe that truncate the precision of the elevation field, or for improperly extracted drainage database files that do not correctly identify outlet locations); more details here
  • Added a check for grids where NEXT is less than their respective RANK ID, which can indicate circular or reverse flow (not valid), among the inline checks for fields read from the drainage database
  • Added a check for grids that contain no active GRUs among the inline checks for fields read from the drainage database
  • Added a check to ensure river classes have been defined if channel routing is active among the inline checks for fields read from the drainage database
  • Generalized the re-weighting of GRUs in grids whose fractions do not add to 100% to be independent of the drainage database file format
  • Added a summary of the soil profile configuration if DIAGNOSEMODE is enabled
  • Added messaging routines for consistent formatting of messages printed to screen and to the diagnostic output file, and for consistent formatting of outputs printed to text-based output files (text format and CSV)
  • Added global exit and abort routines to make simulation exists consistent (where sub-model and sub-modules make use of these codes)
  • Added global output variables to make more variables accessible for outputs and to make outputs consistent across different output files, in particular where aggregated for higher output frequency than the model time-step
  • Improved attributes of the "ic" counter to more easily identify the end of a time-step, day, month, calendar year, etc.., to simplify logic for writing outputs for developers
  • Updated the version to "1398"

Gridded outputs (OUTFIELDSFLAG)

  • Enhanced OUTFIELDSFLAG to support a larger subset of variables (using the added global output variables); the full variable list is here
  • Modified the options available in outputs_balance.txt to be variable-independent such that all available options can be used for all available output variables
  • Added the "tsk" option to print outputs at specific tile points (complements the "tsi" option, which behaves identically but for grids)
  • Added the "gru", "gru_inlude", and "gru_exclude" options to mask gridded outputs for specific GRUs
  • Modified the behavior of "txt" and "csv" output files to include a column of dates (in the first column in the file) by default; the original behavior can be restored with the "no_date" option
  • Disabled the "cum", "acc", "avg", "max", and "min" options, as they are not compatible with how the added global output variables are now aggregated and accumulated
  • Added support for the ALD, ALD_DOY, ALD_ENV, TAVG, TMAX, TMIN, TRNG, and ZOD fields (permafrost diagnostic outputs) and the "ttol" option for the applicable output fields

Inputs and Outputs (general)

  • Changed the order of reading parameter files from INI-r2c-CSV formats to INI-CSV-r2c formats (fields optionally read from the r2c text format parameter file take highest priority)
  • Modified the inline parameter distribution to not assign grid-based values read from MESH_parameters.r2c to tiles where the mosaic ID MID is greater or equal to 100; in those tiles, the values read from the CLASS input file will persist
  • Generalized the mapping of values of the last configured soil layer to all deeper layers to be independent of the CLASS input file (works for all input file formats)
  • Added support for ORGM (optionally with layer specifier) in MESH_parameters.r2c
  • Added the "daily", "monthly", "hourly", "ts", "none", and "all" options to BASINAVGEBFILEFLAG (previously only available for BASINAVGWBFILEFLAG)
  • Removed the HFS and QEVP columns previously available in the Basin_average_energy_balance.csv file and replaced them with the FSIN, FSOUT, ALBT, FLIN, FLOUT, GTE, QH, QE, GZERO, TA, TCAN, CMAS, TSNOW, TPOND, and TBAR (one column for every soil layer, labelled with the soil layer) columns
  • Removed support for the S_moisture.txt and T_temperature.txt input files
  • Added the "controlled_reservoir" option flag in MESH_parameters_hydrology.ini with the "allcols" option to read data from the reservoir input file using all columns (like WATFLOOD); the default behavior remains to read only as many columns as "controlled reservoirs" are defined
  • Added the "daily" option to REACHOUTFLAG to create the MESH_output_reach.csv output file for daily reservoir outputs (one created for each reservoir); the STGCH column contains NO_DATA values in runs using WF_ROUTE because it does not keep track of reservoir storage (the WF_ROUTE reservoir rules are based on an accumulation of inflows)
  • Added the MESH_output_lake_level.csv output file for daily reservoir level output (this file cannot be disabled if reservoirs exist in the setup)

CLASS

  • Added the ability to override the default CLASS time-stepping DELT with TIMESTEPFLAG
  • Restored the ability to allow SAND percent-content to be zero in CLASSB/CLASSBG
  • Fixed where the Soulis formulation for THFC was incorrectly assigned to the deepest layer in mineral soils, instead of to the deepest permeable soil layer in CLASSB/CLASSBG

SVS

RTE

  • Updated the RPN_watroute (RTE) code
  • Added flow initialization in RTE (using the first value read from the streamflow input file, after skipping records)
  • Fixed the line truncation in RTE that results in a coefficient of 0.66 being used in flow calculations, instead of 0.667 as intended
  • Added resume functionality

WF_ROUTE

  • Fixed the accumulation of inflows for reservoir routing in WF_ROUTE

Standalone WATROUTE (RPN_watroute)

  • Updated the RPN_watroute (RTE) code
  • Fixed the line truncation in RTE that results in a coefficient of 0.66 being used in flow calculations, instead of 0.667 as intended

SIMSTATS (AUTOCALIBRATIONFLAG)

  • Updated SIMSTATS (AUTOCALIBRATIONFLAG) to dynamically extend arrays in the absence of explicit simulation start and stop dates (for runs based solely on the availability of forcing data)
  • Changed the behavior of SIMSTATS (AUTOCALIBRATIONFLAG) to create outputs in the general output folder specified in MESH_input_run_options.ini