Page tree

MESH - A Community Hydrology - Land Surface Model


Skip to end of metadata
Go to start of metadata

This page describes how to configure MESH to run SVS version 1.0 and version 2.0 in a "point mode".

Overview

MESH can be configured to run SVS version 1.0 and version 2.0 in a point mode. This process uses a combination of the MESH_input_run_options.ini, MESH_input_soil_levels.txt, and MESH_parameters.txt input files. Compared to traditional MESH configurations, the INI format parameter files are disabled. Driving data can be provided via the CLASS MET format forcing file, or using files in CSV format, or a combination of both.

Page contents:

Step-by-step guide

Meteorological forcing data

Driving data must be prepared in the CLASS MET forcing file or CSV formats. The data must be a continuous time-series with no missing data (i.e., no NO_DATA frames), and must have a consistent time-stepping between frames. The time-series must be in UTC+00 time and consider leap-days (i.e., February 29) on leap-years.

CLASS MET format forcing file

The CLASS MET forcing file is a format borrowed from former standalone release of the Canadian Land Surface Scheme (CLASS). The columns of the file are described below. Sample files may show the file in legacy fixed formatting, though MESH reads the file in free-format. Thus, fields need to separated by whitespace, such as one or more tabs or spaces, but do not necessarily need to follow the exact same formatting as shown. The file contains no header.

The file must be named "basin_forcing.met".

basin_forcing.met (excerpt)
   1   0   274  1994    0.00  337.80 0.0000E+00   10.95 8.4580E-03    0.90   86382.00 0.0000E+00 0.0000E+00
   2   0   274  1994    0.00  337.60 0.0000E+00   10.85 8.4490E-03    0.80   86382.00 0.0000E+00 0.0000E+00
   3   0   274  1994    0.00  337.30 0.0000E+00   10.65 8.3470E-03    0.70   86382.00 0.0000E+00 0.0000E+00
The CLASS MET format forcing file is the only forcing format that MESH expects temperature provided in units of degrees Celsius. Temperature is expected in units of Kelvin in other file formats.
The final two columns in the file are only expected if using BASINFORCINGFLAG with the "rr_sr" option.
The forcing reference heights for thermodynamics (temperature and humidity) and momentum (wind speed) are assumed at 0.995 sigma or should otherwise be specified in the MESH_parameters.txt input file (described later in this page).
ColumnVariableDescriptionUnits
1HOURHour in day (0-23).--
2MINSMinutes in hour (must be in common with the model time-step, such that mod(model time-step, MINS) = 0).--
3JDAYDay in year (must account for leap-days in leap-years).--
4YEARYear (in format YYYY).--
5FSINIncoming shortwave radiation at the surface.W m**-2
6FLINIncoming longwave radiation at the surface.W m**-2
7PRETotal precipitation rate at the surface. If the "rr_sr" option is specified on BASINFORCINGFLAG, this value is still required but not used internally; it is replaced with "PRERN" and "PRESNO" (below).kg m**-2 s**-1 or mm s**-1
8TA

Air temperature at the forcing reference height.

Note: This is the only file that expects temperature in degrees Celsius. If mixing file formats, temperature should be provided in units of Kelvin in other file formats.

degrees C
9QASpecific humidity at the forcing reference height.kg kg**-1
10UVWind speed at the forcing reference height for momentum.m s**-1
11PRESSurface pressure.Pa
12PRERNTotal incoming liquid precipitation rate. Only expected and read if BASINFORCINGFLAG is used with the "rr_sr" option.kg m**-2 s**-1
13PRESNOTotal incoming solid precipitation rate. Only expected and read if BASINFORCINGFLAG is used with the "rr_sr" option.kg m**-2 s**-1
 If the "rr_sr" option in BASINFORCINGFLAG is not used, the separation between liquid and solid phase depends on air temperature and uses a fixed threshold of 0 degree C. It can be modified in the routine runsvs_mesh.F90

CSV format forcing files

Individual time-series can be passed as separate forcing files using the CSV format.

The file contains no header, no date column, and a single column of data. The data must be a continuous time-series with no missing data (i.e., NO_DATA) frames, and must have a consistent time-stepping between frames. The time-series must be in UTC+00 time and consider leap-days (i.e., February 29) on leap-years.

basin_temperature.met (excerpt)
284.11,
284.01,
283.81,
FileVariableDescriptionUnits
basin_shortwave.csvFSINIncoming shortwave radiation at the surface.W m**-2
basin_longwave.csvFLINIncoming longwave radiation at the surface.W m**-2
basin_rain.csvPRETotal precipitation rate at the surface.kg m**-2 s**-1 or mm s**-1
basin_temperature.csvTA

Air temperature at the forcing reference height.

K
basin_humidity.csvQASpecific humidity at the forcing reference height.kg kg**-1
basin_wind.csvUVWind speed at the forcing reference height for momentum.m s**-1
basin_pres.csvPRESSurface pressure.Pa
The "rr_sr" option in BASINFORCINGFLAG cannot be used with CSV forcing file.

Time-stepping

MESH does not read time-stamps or dates from forcing files. In some ways, this is a legacy of how forcing files were originally created for MESH from ECCC numerical weather prediction outputs, but also strategic to remove file seek-times and improve run-time performance. This is why certain file formats, such as files in CSV format, do not contain dates.

The start date corresponding to the first frame of record in forcing files, is passed to MESH as a variable, either in the last line of MESH_parameters_CLASS.ini, if using the INI format parameter files, or with the "start_date=" option on BASINFORCINGFLAG. The sample excerpts on this page specify the start date using the BASINFORCINGFLAG control flag, as using the INI format parameter files is disabled.

The frame length/time-stepping of records in the file is provided either using the HOURLYFLAG control flag, or using the "hf=" option on BASINFORCINGFLAG. The date corresponding to a frame of data is calculated from the specified start date, where the minutes elapsed are determined as the product of the offset of records read from the file and the frame length.

These "start_date=" and "hf=" options of BASINFORCINGFLAG are described in detail here.

Creating and configuring the MESH_input_run_options.ini file

A new text file should be created, named "MESH_input_run_options.ini". This file contains model configuration. The sections of the file are described here.

When adding or removing control flags in MESH_input_run_options.ini, update the "Number of control flags" at the beginning of the section, or the program will exit with an error.

This example MESH_input_run_options.ini file is described in detail below:

MESH_input_run_options.ini
MESH run options input file
##### 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
##### 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, minute
   0   0   0   0 # Stop year, day, hour, minute

Control flags

If control flags are added or removed, the "Number of control flags" at the top of this section must be updated to reflect the number of controls flags that are listed in the file:

----#
    8 # Number of control flags

Descriptions of the active control flags in the example file are as follows:

Options with equal signs (e.g., hf=) must be provided as a single word with no whitespace, such as tabs or spaces, separating the option name, equal sign, and value.
Control FlagOptionDescription
BASINFORCINGFLAG
met

BASINFORCINGFLAG with the "met" option specifies that driving data should be read from the CLASS MET format forcing file. The expected file is named "basin_forcing.met".

The "met" option can be replaced with "csv" to read driving data from forcing files in CSV format instead.

BASINFORCINGFLAG can be replaced or complemented with the BASINRAINFLAG, BASINTEMPERATUREFLAG, etc.., overrides to specify file format on a variable-basis. These overrides are described here. This is also described below.

rr_sr

BASINFORCINGFLAG with the "rr_sr" option activates reading two extra columns in the CLASS MET format forcing file (PRERN and PRESNO, described above). Without this option, the liquid and solid components of precipitation are determined by functions inside the code, provided a single "total precipitation" value.

With the "rr_sr" option, the column corresponding to "total precipitation" (PRE) is still required and read from the file, but is not used internally.

The CLASS MET format forcing file is the only forcing file that uses this option.

start_date=1994100101

MESH does not read time-stamps from forcing files. Thus, it requires the start date to be passed as a variable.

hf=60

The "hf=" option on BASINFORCINGFLAG specifies the frame length of each record in the forcing files in minutes. In this case, it's provided as 60 minutes (e.g., hourly). The record length must be must be in common with the model time-step, such that mod(model time-step, hf) = 0 or mod(hf, model time-step) = 0.

MESH does not read time-stamps from forcing files. Thus, the frame length is required to associate times with records read from file. The date corresponding to a record is calculated from the specified start date, where the minutes elapsed are determined as the product of the offset of records read from the file and the frame length. For this reason, frames in the file must have uniform time-stepping.

If mixing forcing file formats or using separate CSV format files instead, the frame length can be specified before BASINFORCINGFLAG or its overrides using the HOURLYFLAG control flag, or the "hf=" option can be specified on the forcing file flags individually (e.g., if the forcing files have different frame lengths). There are examples of this below.

SHDFILEFLAG
2
For point mode, SHDFILEFLAG must be set to 2 to activate the "point mode" and prevent MESH from searching for a drainage database input file, which contains additional attributes for running fully-distributed hydrological simulations.
INPUTPARAMSFORMFLAG
only
The "only" option on INPUTPARAMSFORMFLAG prevents MESH from searching for the INI format parameter files.
txt
The "txt" option on INPUTPARAMSFORMFLAG tells MESH to read the MESH_parameters.txt input file.
SOILINIFLAG
0
SOILINIFLAG can be configured to optionally redistribute soil texture parameters when their sum adds to greater than 100% of the soil triangle.
NRSOILAYEREADFLAG
3

NRSOILAYEREADFLAG controls how many values to read from file for soil-related parameters and initial conditions. In this case, the option 3 tells MESH to expect three values for soil-related parameters and initial conditions when reading data from file. If more than 3 values exist in the file, they are ignored. If more than three soil layers exist in the discretization, the values of the third layer are applied to all deeper layers.

This flag is useful to assign values to deeper layers when many layers exist in the discretization that are assumed to all be of the same soil type, in which case those layers do not need to be parameterized and initialized by repeating values in the input file.

This flag is described in detail here.

To parameterize and initialize all layers explicitly, set the flag to 1. To parameterize and initialize a subset of the layers, between 3 and the total number of layers, set the flag value equal to the number of layers to read from file.

RUNMODE
runsvs
To activate SVS, RUNMODE must include the "runsvs" option, or MESH will run with the default Canadian Land Surface Scheme (CLASS) instead.
noroute
To run in point mode, RUNMODE must include the "noroute" option to disable distributed routing routines, which require additional hydrological attributes and basin information not included in the subset of input files used for "point mode".
DIAGNOSEMODE
on

DIAGNOSEMODE can be optionally activated to print additional diagnostic information during the initialization of the model to screen and to MESH_output_echo_print.txt.

The option can be disabled by changing the setting from "on" to "off".

TIMESTEPFLAG
5

TIMESTEPFLAG specifies the time-step in minutes used by the land surface scheme, in this case of SVS. In point mode, as this is the only process-based module active in the model, TIMESTEPFLAG defines the model time-step.

Diagnostic point outputs

"Diagnostic point outputs" can be optionally activated by changing the "Number of output points" to 1. However, creating diagnostic outputs saves a significant amount of data to file at every time-step of the model, which creates very large files and impacts model run-time performance. Using these outputs is only recommended for very specific diagnostic purposes. Where possible, creating outputs using OUTFILESFLAG (configured with outputs_balance.txt) is recommended instead. A list of all of the variables that are available as MESH outputs via OUTFILESFLAG is here.

In point mode, only 1 grid and 1 GRU are used (a single tile within a single "unit grid") so only 1 output point should be specified in this section.

The outputs will be written inside the "output directory". MESH does not create directories by itself, so the folder must be created and already exist before the simulation is run, or the program will abort with an error. The folder name cannot contain any whitespace, such as tabs or spaces.

To write the outputs in the same location as the program (e.g., alongside the input files), set the "output directory" to a single period ".".

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

General outputs

Most model outputs are saved to the general "output directory". Outputs include general model outputs, the basin-average outputs files, and outputs created via OUTFILESFLAG, if enabled.

The folder name must be less than 10 characters (the same number of dashes in the line above where the "output directory" is specified). MESH does not create directories by itself, so the folder must be created and already exist before the simulation is run, or the program will abort with an error. The folder name cannot contain any whitespace, such as tabs or spaces.

To write the outputs in the same location as the program (e.g., alongside the input files), set the "output directory" to a single period ".".

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

Simulation run times

Simulation run times specify the simulation window. If a specific date for the simulation start date is provided, it must occur on or after the start date corresponding to the first frame in the forcing files. If the simulation start date occurs after this start date, MESH will automatically skip the necessary number frames in the forcing files.

If the simulation start date is specified as all zeros, the simulation starts from the first frame in the forcing files, such that the simulation runs from when driving data are available.

The simulation stop date is not included in the simulation. The simulation ends in the last time-step just before the specified simulation stop date. Thus, to run a full year of data, the simulation stop date is not December 31 23:55 (assuming 5-minute model time-step), but rather January 1 00:00. This assumption is by design, to simplify how the simulation stop date is specified in this file.

If the simulation stop date is specified as all zeros, the simulation runs until it runs out of driving data.

The simulation start and stop dates are described in detail here.

MESH_input_run_options.ini
##### Simulation run times #####
---#---#---#---#
   0   0   0   0 # Start year, day, hour, minute
   0   0   0   0 # Stop year, day, hour, minute

BASINFORCINGFLAG and forcing file considerations

If using driving data in the CLASS MET format forcing file, BASINFORCINGFLAG must be included in the list of control flags with the "met" option.

In the following file,

  • "met" specifies that driving data should be read from the CLASS MET format forcing file
  • "start_date=1994100101" specifies that the first frame of data occurs on October 1, 1994 at 01:00
  • "hf=60" specifies that the frame length/time-stepping of the file is 60 minutes (e.g., hourly)
MESH_input_run_options.ini (excerpt)
BASINFORCINGFLAG         met rr_sr start_date=1994100101 hf=60

If using driving data in CSV format where the frame length is consistent between all files, BASINFORCINGFLAG can be used with the "csv" option.

In the following file,

  • "csv" specifies that driving data should be read from CSV format forcing files
  • "start_date=1994100101" specifies that the first frame of data occurs on October 1, 1994 at 01:00
  • "hf=60" specifies that the frame length/time-stepping of the file is 60 minutes (e.g., hourly)
MESH_input_run_options.ini (excerpt)
BASINFORCINGFLAG         csv start_date=1994100101 hf=60

If the driving data are in CSV format, but the frame length is not consistent between files, the BASINFORCINGFLAG overrides can be used to specify "hf=" on a per-flag basis. BASINFORCINGFLAG should be listed before overrides for specific files.

In the following file,

  • The options of BASINFORCINGFLAG are applied for all fields
    • "csv" specifies that driving data should be read from CSV format forcing files
    • "start_date=1994100101" specifies that the first frame of data occurs on October 1, 1994 at 01:00
    • "hf=60" specifies that the frame length/time-stepping of the file is 60 minutes (e.g., hourly)
  • The options of BASINRAINFLAG override these options of the total precipitation field (PRE) specifically
    • "hf=360" specifies that the frame length/time-stepipng of the "basin_rain.csv" forcing file is actually 360 minutes (e.g., 6-hourly)
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. For the CSV format, the numeric code is 2.
MESH_input_run_options.ini (excerpt)
BASINFORCINGFLAG         csv start_date=1994100101 hf=60
BASINRAINFLAG          2 hf=360  

The above approach can also be used to use the CLASS MET and CSV format forcing files together. For example, to read a background field of station data from the CLASS MET format file, and overwrite specific columns with revised or modified values read from CSV format files. BASINFORCINGFLAG should be listed before overrides for specific files.

In the following file,

  • HOURLYFLAG is used to specify the frame length as 30 minutes (e.g., half-hourly), which applies for all forcing files
  • BASINFORCINGFLAG is specified with the "met" option to read driving data from the CLASS MET format forcing file
  • BASINRAINFLAG with option 2 specifies that total precipitation should also be read from the "basin_rain.csv" CSV format file, which will overwrite "PRE" read from the CLASS MET format forcing file
  • BASINTEMPERATUREFLAG with option 2 specifies that temperature should also be read from the "basin_temperature.csv" CSV format file, which will overwrite "TA" read from the CLASS MET format forcing file
If HOURLYFLAG is not included when BASINFORCINGFLAG and/or multiple overrides are included, and no "hf=" option is specified on those files, MESH will assume the record length in all forcing files is 30 minutes (e.g., half-hourly). This is described here.
If HOURLYFLAG precedes BASINFORCINGFLAG or its overrides, and those flags specify the "hf=" option, the "hf=" option will override the HOURLYFLAG value.
MESH_input_run_options.ini (excerpt)
HOURLYFLAG            30
BASINFORCINGFLAG         met
BASINRAINFLAG          2
BASINTEMPERATUREFLAG   2

Creating and configuring the MESH_input_soil_levels.txt file

A new text file should be created, named "MESH_input_soil_levels.txt". This file defines the soil layer discretization. The file is described here.

MESH determines the number of soil layers in the domain from reading the number of lines in this file. The first column in the file identifies the soil layer thickness. The second column identifies the depth from the surface to the bottom of the soil layer. Thus, the value in the second column in the last row of the file is the total depth of the soil profile.

SVS contains methods for re-mapping the soil texture parameters of the soil profile to a pre-defined soil layer discretization of specific datasets. If re-mapping of the soil profile is not required, the "soiltext" option of SVS must be set to "NIL". This variable and option are specified in MESH_parameters.txt, and described in the next section.

An example MESH_input_soil_levels.txt file:

MESH_input_soil_levels.txt
      0.05      0.05 !> delz(1)/dl_svs(1)
      0.05       0.1 !> delz(2)/dl_svs(2)
       0.1       0.2 !> delz(3)/dl_svs(3)
       0.2       0.4 !> delz(4)/dl_svs(4)
       0.6       1.0 !> delz(5)/dl_svs(5)
       1.0       2.0 !> delz(6)/dl_svs(6)
       1.0       3.0 !> delz(7)/dl_svs(7)
The number of soil layers in the default version of MESH-SVS is restricted to 12

Note that the vertical discretization of the sample file above corresponds to the default soil profile used for SVS in GEM-Hydro (ECCC prediction system), which includes 7 soil layers and max. depth of 3m.

Creating and configuring the MESH_parameters.txt file

A new text file should be created, named "MESH_parameters.txt". This file can contain options, parameters, and variables for specific process-modules. In this case, the file has been configured for SVS. The file, structure, and fields supported by the file are described here.

This example MESH_parameters.txt file is described in detail below. The file shown below is adapted for SVS1. Please refer to the test case on the GitHub repo to get an example of a file adapted for SVS2.

MESH_parameters.txt
! TXT (free-format) MESH configuration file.
!
! See important notes below to use this file for basin configuration (e.g., to run point mode).
!  When running in distributed mode, 'npoints' should correspond to the number of GRUs
!  determined from the distributed database (LSS or drainage database, depending on operating mode).
!  When running in point mode, 'npoints' defines the number of subbasins/simulation points.
! See details on this file format here: https://wiki.usask.ca/display/MESH/MESH_parameters.txt

! Basin information.
! Only a single column (single point) for point mode.
!npoints     ----- 1
deglat         45.30 !degrees
deglng          5.77 !degrees

! Forcing configuration.
observed_forcing      height !height: uses heights directly.
!npoints     ----- 1
zusl            10.0 !m, for momentum
ztsl             1.5 !m, for temperature/humidity

! Surface (WATDRN).
! npoints     ----- 1
slop           0.005 !m m**-1
draindens       0.05 !m m**-2


! Soils.
soiltext                 NIL !NIL: required to use soil_levels.txt as-is
! By default, values for 3 layers are required and only read. The values of the third layer are applied to all deeper layers.
! To override this behaviour, activate "NRSOILLAYEREADFLAG" in MESH_input_run_options.ini with an option.
! See details here: https://wiki.usask.ca/display/MESH/NRSOILAYEREADFLAG
!  Validate the mapping by activating "DIAGNOSEMODE" in MESH_input_run_options.ini.
!  A summary of the soil layers, texture values, and mapping are then printed to MESH_output_echo_print.txt.
!nlayers     ----- 1 ----- 2 ----- 3 ----- 4 ----- 5 ----- 6 ----- 7
sand            60.0    60.0    60.0 !%
clay            30.0    30.0    30.0 !%
wsoil          0.083   0.086   0.098 !vol. content
isoil            0.0     0.0     0.0 !vol. content
! Special values not tied to soil layer scheme.
!nlayers     ----- 1 ----- 2
tground       284.81  284.43 !Kelvin, only 2 values for svs1

! Vegetation canopies.
! Map land cover to the most appropriate land cover in SVS.
! Values are required for 26 pre-defined categories.
!ncanopies   ----- 1 ----- 2 ----- 3 ----- 4 ----- 5 ----- 6 ----- 7 ----- 8 ----- 9 ---- 10 ---- 11 ---- 12 ---- 13 ---- 14 ---- 15 ---- 16 ---- 17 ---- 18 ---- 19 ---- 20 ---- 21 ---- 22 ---- 23 ---- 24 ---- 25 ---- 26
!                sea glacier in-lake ever-nl ever-bl deci-nl deci-bl trop-bl  dry-tr ever-sh deci-sh thor-sh shor-gr long-gr   crops    rice   sugar   maize  cotton  irr-cr   urban  tundra   swamp  desert mx-tree   mx-sh
vf               0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     1.0     0.0     0.0     0.0     0.0 !fraction
!nlayers     ----- 1 ----- 2
tvege          285.7   285.7 !Kelvin
!npoints     ----- 1
wveg             0.0 !kg m**-2

! Snow.
! Category: High veg.
!nlayers     ----- 1 ----- 2
tsnowveg      273.16  273.16 !Kelvin
!npoints     ----- 1
snvdp            0.0 !m
snvden           0.0 !kg m**-3, replaces 'snoro'; replaced if 'snoro' is listed after this line
snval            0.0 !fraction
wsnv             0.0 !kg m**-2
! Category: Low veg. and bare ground.
!nlayers     ----- 1 ----- 2
tsnow         273.16  273.16 !Kelvin
!npoints     ----- 1
snodpl           0.0 !m
snoden           0.0 !kg m**-3, replaces 'snoro'; replaced if 'snoro' is listed after this line
snoal            0.0 !fraction
wsnow            0.0 !kg m**-2

The lines in the file are read as whitespace delimited. All fields should be separated by one or more tabs or spaces. Samples may show aesthetic spacing for readability, but the spacing between fields and values does not have to be consistent from one line to the next.

Review the spacing section on the support page for this file for more information.

Review the file structure section on the support page for this file for tips for visualizing the file with syntax highlighting to more easily identify comments.
Variables that have no specified 'Default Value' must be included in the file, and include valid user-specified values.

Basin configuration (needed for both versions of SVS)

Coordinates should be specified in regular "LATLONG" projection.
Field NameNo. of ValuesTypeDescriptionDefault ValueUnits
DEGLAT(see note above)RealLatitude of point.--degrees
DEGLNG(see note above)RealLongitude of point.--degrees

Climate forcing options (needed for both versions of SVS)

"OBSERVED_FORCING" should be specified as "height" for observatory data that come from site instrumentation. However, "OBSERVED_FORCING" is still allowed to be "sigma" with respective sigma levels in point mode, if relevant for the forcing files. For example, if these data are point time-series extracted from numerical weather prediction model outputs.
Field NameNo. of ValuesTypeDescriptionDefault ValueUnits
OBSERVED_FORCING1CharacterSpecifies the type of driving data. Must be one of "sigma" or "height".sigma--

Only if "OBSERVED_FORCING" is specified as "sigma":

Field NameNo. of ValuesTypeDescriptionDefault ValueUnits
SIGMA_U1RealReference level of forcing data for momentum.0.995sigma
SIGMA_T1RealReference level of forcing data for momentum.0.995sigma

Only if "OBSERVED_FORCING" is specified as "height":

Field NameNo. of ValuesTypeDescriptionDefault ValueUnits
ZUSL1RealReference height of forcing data for momentum.--m
ZTSL1RealReference height of forcing data for temperature and humidity.--m

SVS version

Field NameNo. of ValuesTypeDescriptionDefault ValueUnits
SCHMSOL1CharacterVersion of SVS to use (SVS1 or SVS2).  Two possible values: SVS for SVS1 and SVS2 for SVS2.SVS --

Soils configuration (needed for both versions of SVS)

The number of soil layers is derived from reading MESH_input_soil_levels.txt.
SVS contains methods for re-mapping the soil texture parameters of the soil profile to a pre-defined soil layer discretization of specific datasets. If re-mapping of the soil profile is not required, the "soiltext" option of SVS must be set to "NIL". This option is recommnded for point-scale applications.
Field NameNo. of ValuesTypeDescriptionDefault ValueUnitsSupported Since
SOILTEXT1Character

Specifies the soils database for mapping soils information. Must be one of "GSDE", "SLC", "SOILGRIDS", or "NIL". See the SVS documentation for more information about soil mapping.

Set to "NIL" to use the "SAND" and "CLAY" values as read from the file, without re-mapping.

NIL--r1641
KHYD1RealNumber of permeable soil layers for the water balance.6--r1641

Physiographic characteristics (needed for both versions of SVS)

NRSOILAYEREADFLAG can be used to configure how many values for each soil-related parameter to read from file.

Legend:

  • NLANDTYPE: Number of land cover types
  • NSOIL: Number of soil layers
Field NameNo. of ValuesTypeDescriptionDefault ValueUnits
SLOP(see note above)RealTopographic slope.--m m**-1
DRAINDENS(see note above)RealDrainage density.--m m**-2
SAND1->NSOILRealSand content.--%
CLAY1->NSOILRealClay content.--%
VF1->NLANDTYPERealActive fraction for each vegetation type. The 26 land cover types expected by SVS are pre-defined. See this page for more information. The sum of VF fractions should add to 1.0.--fraction
Z0V1->NLANDTYPEReal

Aerodynamic roughness height.

Default: SVS uses default values for each vegetation type. See the this page for more information.

User-defined: The roughness length is specified for each vegetation type in MESH_parameters.txt (see the example below). In this case, an average value is calculated using the VF fraction.

--m
The sum of all VF fractions should add to 1.0.

User-defined roughness length (Z0V). Only values corresponding to an active vegetation type with VF > 0.0 need to be defined (see below).

MESH_parameters.txt
! Vegetation canopies.
! Map land cover to the most appropriate land cover in SVS.
! Values are required for 26 pre-defined categories.
!ncanopies   ----- 1 ----- 2 ----- 3 ----- 4 ----- 5 ----- 6 ----- 7 ----- 8 ----- 9 ---- 10 ---- 11 ---- 12 ---- 13 ---- 14 ---- 15 ---- 16 ---- 17 ---- 18 ---- 19 ---- 20 ---- 21 ---- 22 ---- 23 ---- 24 ---- 25 ---- 26
!                sea glacier in-lake ever-nl ever-bl deci-nl deci-bl trop-bl  dry-tr ever-sh deci-sh thor-sh shor-gr long-gr   crops    rice   sugar   maize  cotton  irr-cr   urban  tundra   swamp  desert mx-tree   mx-sh
vf               0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     1.0     0.0     0.0     0.0     0.0 !fraction
z0v              0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0     0.0   0.025     0.0     0.0     0.0     0.0 !roughness length 

Options available in SVS 1

Field NameTypeDescriptionPossible valuesDefault Value
LSOIL_FREEZING_SVS1BooleanActivate soil freezing option in SVS1.true. or .false. .false.
LWATER_PONDING_SVS1BooleanActivate water ponding scheme in SVS1

.true. or .false.

.false.
These options needs to be defined in MESH_parameters.txt before defining the initial conditions (see below)

Options for multi-layer snowpack scheme in SVS 2.0

More details about the physical options in the multiphysical version of Crocus are availale in Lafaysse et al. (2017).

Field NameTypeDescriptionPossible valuesDefault Value
HSNOWSCHEMECharacterSnowpack scheme to use (Explicit Snow or Crocus)ES, CROES
NSLIntegerNumber of snow layers

6, 9, 12 for ES; Up to 50 for CRO

20
HSNOWDRIFT_CROCharacterOption for the snowdrift scheme for Crocus: Mechanical transformation of snow grain and compaction and effect of wind on falling snow properties

NONE: No snowdrift scheme

DFLT: falling snow falls as purely dendritic

GA01: Gallee et al 2001

VI13: Vionnet et al 2013

VI13
LSNOWDRIFT_SUBLIMBooleanActivate mass loss due to blowing snow sublimation in ES and Crocus.true. or .false. .true.
HSNOWMETAMOCharacterOption for the metamorphism scheme for Crocus

C13: Carmagnola et al 2014

T07: Taillandier et al 2007

F06: Flanner et al 2006

C13
HSNOWRADCharacterOption for the radiative transfer scheme for Crocus

B92: Brun et al 1992

T17: (Tuzet et al. 2017) (Libois et al. 2013) TARTES with impurities content scheme

B92
HSNOWFALLCharacterOption for the falling snow density for Crocus

V12: Vionnet et al. 2012 from Brun et al. 1989

A76: Anderson et al. 1976

S02: Lehning el al. 2002

P75: Pahaut 1975

NZE: Constant density 200 kg/m3 (defined snowcro.F90 )

V12
HSNOWCONDCharacterOption for the thermal conductivity scheme for Crocus

Y81: default Crocus from Yen et al. 1981

I02: ISBA_ES snow conductivity parametrization (Boone et al. 2002)

C11: Calonne et al. 2011 snow conductivity parametrization

Y81
HSNOWHOLDCharacterOption for the liquid water content scheme for Crocus

B92: default Crocus from Brun et al. 1992 or Vionnet et al. 2012 (Default in SVS2)

B02: ISBA_ES parametrization (Boone et al. 2002)

O04: CLM parametrization (Oleson et al 2004)

S02: SNOWPACK aprametrization (Lehning et al 2002)

B92
HSNOWCOMPCharacterOption for the compaction scheme for Crocus

B92: default Crocus from Brun et al. 1992 or Vionnet et al. 2012 (Default in SVS2)

S14: use the settling param of Schleef et al. (2014) for fresh snow (less than 2 days)

T11: param of snow viscosity from Teufelsbauer (2011)

B92
LOUT_SNOWPROFILEBooleanCreate output file containing detailed information on snowpack layering for Crocus simulations. See below for more information on the model outputs.True or FalseFalse
NPROFILE_DAYIntegerNumber of snow profiles per day when  LOUT_SNOWPROFILE=True.1, 2 , 3, 4, 6, 8, 12, 244
LOUT_SNOW_ENBALBooleanCreate output file containing information on the surface energy balance of the snowpack.True or FalseFalse

Initial conditions (prognostic variables, depending on the version of SVS)

NRSOILAYEREADFLAG can be used to configure how many values for each soil-related parameter to read from file.
In its current implementation in MESH, SVS2 2.0 assumes initial snow free conditions. Only the number of snow layers is provided by the users (see previous above).

Legend:

  • NSOIL: Number of soil layers
Field NameNo. of ValuesTypeDescriptionDefault ValueUnitsVersion of SVS
WSOIL1->NSOILRealLiquid water content in the soil.--m**3 m**-31 and 2
ISOIL1->NSOILRealFrozen water content in the soil. (only used with soil freezing option in SVS1 and with multi-layer soil scheme in SVS2)--m**3 m**-31 and 2
TGROUND1->2RealSoil temperature of the Force Resrore scheme (index 1: skin temperature; index 2: mean).--K1
TPSOIL1 → NSOILRealSoil temperature in the soil below low-lying vegetation and bare ground (with soil freezing option in SVS1 and with multi-layer scheme in SVS2)--K1 (with freezing) and 2
TPSOILV1 → NSOILRealSoil temperature in the soil below high vegetation (multi-layer scheme in SVS2)--K2
TPERM1RealDeep soil temperature used as a lower boundary conditions for the soil column in SVS1 with soil freezing actrivated and in SVS2--K1 (with freezing) and 2
TVEGE1->2RealVegetation canopy temperature (index 1: skin temperature; index 2: mean).--K1 and 2
WVEG1RealLiquid water retained in the vegetation canopy.--kg m**-21 and 2
TSNOW1->2RealSnow temperature over low-lying vegetation and bare ground (index 1: skin temperature; index 2: mean).--K1
SNODPL1RealSnow depth over low-lying vegetation and bare ground.--m1
SNODEN1RealSnow density over low-lying vegetation and bare ground.--kg m**-31
SNOAL1RealSnow albedo over low-lying vegetation and bare ground.----1
WSNOW1RealLiquid water retained in the snowpack for low-lying vegetation and bare ground.--kg m**-21
TSNOWVEG1->2RealSnow temperature below high vegetation (index 1: skin temperature; index 2: mean).--K1
SNVDP1RealSnow depth below high vegetation.--m1
SNVDEN1RealSnow density below high vegetation.--kg m**-31
SNVAL1RealSnow albedo below high vegetation.----1
WSNV1RealLiquid water retained in the snowpack below high vegetation.--kg m**-21
WATPOND1RealHeight of ponded water (if LWATER_PONDING_SVS1 is active)--m1

Running the model

Once the necessary input files have been created, the folder should contain the following files:

The folder may contain additional files if driving data are provided using CSV format.
FileFile TypeDescription
basin_forcing.metInput fileCLASS MET format forcing file (contains driving data)
MESH_input_run_options.iniInput fileMESH run configuration
MESH_input_soil_levels.txtInput fileSoil layer discretization
MESH_parameters.txtInput fileParameter file (also contains process configuration flags and initial conditions)
sa_meshExecutable/binary programStandalone MESH program

With these files and MESH_input_run_options.ini properly configured, running MESH for the point mode is exactly the same as for any model setup. To run the model, run the "sa_mesh" program.

Because no routing process is enabled, MESH will print a time-series of only three variables to screen. These are the same three columns that print to the end of the line in a regular MESH run: the basin-average precipitation, evapotranspiration, and runoff. In a point run, the "basin" is in fact a "unit grid", so these are the precipitation, evapotranspiration, and runoff amounts of the SVS column.

The format of the dates printed to screen can be configured to print data less frequently and/or to print conventional calendar days to screen by configuring the PRINTSIMSTATUS control flag.


Model outputs when using SVS-2

Outputs of SVS2 are available in CSV format. Depending on the variable LOUT_SNOWPROFILE defined in MESH_parameter.txt (see above), 2 or 3 output files are available. More output files can be easily added by the users.

Output FileAvailabilityFrequencyDescription
svs2_soil_hourly.csvAlwayshourlySoil prognostic variables (temperature, liquid and ice water content)
svs2_snow_bulk_hourly.csvAlwayshourlyBulk snow variables for snowpack above bare-ground and low vegetation
svs2_snow_enbal_hourly.csvOnly if LOUT_SNOW_ENBAL = TRUEhourlyVariables related to energy and mass balance of snowpack above bare-ground and low vegetation
svs2_snow_profile_hourly.csvOnly if LOUT_SNOW_PROFILE = TRUEDepends on NPROFILE_DAYDetailed layering of simulated snow physical properties for the snowpack above bare-ground and low vegetation
A post-processing routine has been developped to combine all the outputs in CSV format into a single file in NetCDF format. See the test case on the GitHub repository of MESH-SVS.

svs2_soil_hourly.csv

Variable NameNo. of ValuesDescriptionUnits
WSOIL1->NSOILLiquid water content in the soil.m**3 m**-3
ISOIL1->NSOILFrozen water content in the soil.m**3 m**-3
TPSOIL1 → NSOILSoil temperature in the soil below low-lying vegetation and bare groundK
TPSOILV1 → NSOILSoil temperature in the soil below high vegetationK

svs2_snow_bulk_hourly.csv: For snowpack above bare ground and low-vegetation

Variable NameNo. of ValuesDescriptionUnits
SNOMA1Snow Water Equivalentkg m**-2
SNODP1Snow Depthm
SNODEN1Bulk Snow Densitykg m**-3
SNOALB1Snow Albedo -
WSNO1Total liqud water content of the snowpackkg m**-2
TSNO_SURF1Snow surface temperatureK
RSNOW_AC1Cumulated liquid water runoff at the bottom of the snowpack (reset to 0 day at 12 UTC)kg m**-2
RAINRATE1Liquid Precipitation Ratekg m**-2 s**-1
SNOWRATE1Solid Precipitation Ratekg m**-2 s**-1
The cumulated variables (such as  RSNOW_AC) is transfromed into cumulated variables over the full range of the model integration when converting the csv file into NetCDF (see https://github.com/VVionnet/MESH_SVS/blob/master/test_case/generate_nc_output.py). 

svs2_snow_enbal_hourly.csv: For snowpack above bare ground and low-vegetation.

Positive fluxes are counted towards the snowpack

Variable NameNo. of ValuesDescriptionUnits
SNO_RNET1Net radiative flux at the surface of the snowpackW m**-2
SNO_SWNET1Net shortwave flux at the surface of the snowpackW m**-2
SNO_LWET1Net longwave flux at the surface of the snowpackW m**-2
SNO_LE1Latent Heat flux at the surface of the snowpack W m**-2
SNO_H1Sensible Heat flux at the surface of the snowpackW m**-2
SNO_BSUBL1Rate of mass loss to due blowing snow sublimationkg m**-2 s**-1
SNO_G1Ground heat flux at the snow/soil interfaceW m**-2
SNO_HRAIN1Heat brought by rainfallW m**-2

svs2_snow_profile_hourly.csv: For snowpack above bare ground and low-vegetation

Variable NameNo. of ValuesDescriptionUnits
SNOMA_ML1 → NSLSnow Water Equivalent per layerkg m**-2
SNODEN_ML1 → NSLSnow Density per layerkg m**-3
SNOAGE_ML1 → NSLSnow Age per layerdays
SNODOPT_ML6
1 → NSLSnow Optical Diameter per layerm
SNOSPH_ML1 → NSLSnow Sphericity per layer -
SNOHIST_ML1 → NSLSnow Historical variable per layer-
TSNOW_ML1 → NSLSnow temperature per layerK
WSNOW_ML1 → NSLSnow liquid water content per layerkg m**-2
The thickness of each snow layer in Crocus can be derived by computing the ratio SNOMA_ML/SNODEN_ML (in meter).
The snow Surface Specific Area (SSA, in m**2 kg**-1 ) can be derived for each layer from the relationship SNOSSA_ML = 6/( SNODOPT_ML * rho_ice)  where rho_ice is the ice density (917 kg m**-3). See Carmagnola et al (2014) for more details.

Model outputs when using SVS1

Outputs of SVS1 are available in CSV format. Two files are currently available (see below). More output files can be easily added by the users.

A post-processing routine has been developped to combine all the outputs in CSV format into a single file in NetCDF format. See the test case on the GitHub repository of MESH-SVS.
Output FileAvailabilityFrequencyDescription
svs1_soil_hourly.csvAlwayshourlySoil prognostic variables (temperature, liquid and ice water content)
svs1_snow_bulk_hourly.csvAlwayshourlyBulk snow variables for snowpack above bare-ground and low vegetation and snowpack below high vegetation

svs1_soil_hourly.csv

Variable NameNo. of ValuesDescriptionUnits
WSOIL1->NSOILLiquid water content in the soil.m**3 m**-3
ISOIL1->NSOILFrozen water content in the soil.m**3 m**-3
TPSOIL1 → NSOILSoil temperature in the soil (availale if soil freezing module is activated)K
TGROUND2Surface and deep temperature for bare ground (from the Force Restore scheme)K
TVEG2Surface and deep temperature for vegetation (from the Force Restore scheme)K

svs1_snow_bulk_hourly.csv:

Variable NameNo. of ValuesDescriptionUnits
SNOMA1Snow Mass for snowpack above bare-ground and low vegetationkg m**-2
SNODP1Snow Depth for snowpack above bare-ground and low vegetationm
SNODEN1Bulk Snow Density for snowpack above bare-ground and low vegetationkg m**-3
SNOALB1Snow Albedo for snowpack above bare-ground and low vegetation -
WSNO1Total liqud water content of the snowpack above bare-ground and low vegetationkg m**-2
TSNO2Surface and deep snow temperature (from the Force Restore scheme) for snowpack above bare-ground and low vegetationK
SNVMA1Snow Mass for snowpack below high vegetationkg m**-2
SNVDP1Snow Depth for snowpack below high vegetationm
SNVDEN1Bulk Snow Density for snowpack below high vegetationkg m**-3
SNVALB1Snow Albedo for snowpack below high vegetation -
WSNV1Total liqud water content of the snowpack below high vegetationkg m**-2
TSNV2Surface and deep snow temperature (from the Force Restore scheme) for snowpack below high vegetationK

Related articles