Page tree

MESH - A Community Hydrology - Land Surface Model


Skip to end of metadata
Go to start of metadata

The NRSOILLAYEREADFLAG control flag controls the number of layers to read from MESH_parameters_CLASS.ini or MESH_parameters.txt when reading soil-related parameters and initial values.

Page contents:

Available options

OptionDescriptionSupported since
0No effect, the flag is disabled. Three values are expected for all soil-related parameters and initial values when reading from MESH_parameters_CLASS.ini or MESH_parameters.txt.r747
1Read as many values as the total number of soil layers (NSL) defined in MESH_input_soil_levels.txt for all soil-related parameters and initial values from MESH_parameters_CLASS.ini or MESH_parameters.txt.
<N>

Read the specified number of <N> values for all soil-related parameters and initial values from MESH_parameters_CLASS.ini and MESH_parameters.txt. The value must be greater than 3 and will be automatically limited to the total number of soil layers (NSL) defined in MESH_input_soil_levels.txt:

`3 < N <= "NSL"`
r1027

Examples

Behaviour without this option (NRSOILAYEREADFLAG 0)

Without activating NRSOILAYEREADFLAG, three values for each soil-related parameter and initial value field are required in MESH_parameters_CLASS.ini or MESH_parameters.txt, regardless of the number of soil layers defined in MESH_input_soil_levels.txt:

MESH_parameters_CLASS.ini (excerpt)
      70.0      70.0      70.0  !> SAND(1:3)
      30.0      30.0      30.0  !> CLAY(1:3)
       0.0       0.0       0.0  !> ORGM(1:3)
       5.0       5.0       5.0       5.0       0.0       5.0  !> TBAR(1:3)/TCAN/TSNO/TPND
       0.2       0.2       0.2       0.0       0.0       0.0       0.0  !> THLQ(1:3)/THIC(1:3)/ZPND

If more than three soil layers are defined in MESH_input_soil_levels.txt, the respective values of the third layer are copied to the additional layers for these fields:

do j = 4, NSL
  sand(:, j) = sand(:, 3)
  clay(:, j) = clay(:, 3)
  orgm(:, j) = orgm(:, 3)
  tbar(:, j) = tbar(:, 3)
  thlq(:, j) = thlq(:, 3)
  thic(:, j) = thic(:, 3)
end do
The mapping of these fields from the lowest parameterized layer to lower layers happens automatically inside the MESH code. This is exactly the same process that occurred in MESH prior to the addition of the NRSOILAYEREADFLAG control flag.

NRSOILAYEREADFLAG 1

When NRSOILAYEREADFLAG is activated with option 1, no mapping is done and the same number of values must exist for the soil-related parameters and initial values in MESH_parameters_CLASS.ini as the total number of soil layers (NSL) defined in MESH_input_soil_levels.txt.

Example

NRSOILAYEREADFLAG is activated with option 1 in MESH_input_run_options.ini:

MESH_input_run_options.ini (excerpt)
##### Control Flags #####
----#
    1 # Number of control flags
NRSOILAYEREADFLAG      1

The number of soil layers defined in MESH_input_soil_layers.txt is 4:

MESH_input_soil_levels.txt
       0.1       0.1  !> DELZ/ZBOT (Layer 1)
      0.25      0.35  !> DELZ/ZBOT (Layer 2)
      0.75       1.1  !> DELZ/ZBOT (Layer 3)
       3.0       4.1  !> DELZ/ZBOT (Layer 4)

The number of values for each of the soil-related parameters and initial values in MESH_parameters_CLASS.ini must be changed from 3 to 4:

MESH_parameters_CLASS.ini (excerpt)
      70.0      70.0      70.0      70.0  !> SAND(1:4)
      30.0      30.0      30.0      30.0  !> CLAY(1:4)
       0.0       0.0       0.0       0.0  !> ORGM(1:4)
       5.0       5.0       5.0       5.0       5.0       0.0       5.0  !> TBAR(1:4)/TCAN/TSNO/TPND
       0.2       0.2       0.2       0.2       0.0       0.0       0.0       0.0       0.0  !> THLQ(1:4)/THIC(1:4)/ZPND

NRSOILAYEREADFLAG <n>

When NRSOILAYEREADFLAG is activated with an option > 3 but less than the total number of soil layers (NSL), a similar mapping is done as when NRSOILAYEREADFLAG is disabled, but the lowest parameterized layer used to assign values to lower layers is the layer specified as <n>.

If <n> is set equal to NSL, the the option is equivalent to "NRSOILAYEREADFLAG 1".

Example

NRSOILAYEREADFLAG is activated with option <n> in MESH_input_run_options.ini, where <n> is set to 4 to read values for 4 soil layers:

MESH_input_run_options.ini (excerpt)
##### Control Flags #####
----#
    1 # Number of control flags
NRSOILAYEREADFLAG      4

The number of soil layers defined by MESH_input_soil_levels.txt is 6:

MESH_input_soil_levels.txt
       0.1       0.1  !> DELZ/ZBOT (Layer 1)
      0.25      0.35  !> DELZ/ZBOT (Layer 2)
      0.75       1.1  !> DELZ/ZBOT (Layer 3)
       1.0       2.1  !> DELZ/ZBOT (Layer 4)
       1.0       3.1  !> DELZ/ZBOT (Layer 5)
       1.0       4.1  !> DELZ/ZBOT (Layer 6)

The number of values for each of the soil-related parameters and initial values in MESH_parameters_CLASS.ini must be changed from 3 to 4 (not to 6, which is the total number of soil levels, but only to the value specified as the option <n> value):

MESH_parameters_CLASS.ini (excerpt)
      70.0      70.0      70.0      70.0  !> SAND(1:4)
      30.0      30.0      30.0      30.0  !> CLAY(1:4)
       0.0       0.0       0.0       0.0  !> ORGM(1:4)
       5.0       5.0       5.0       5.0       5.0       0.0       5.0  !> TBAR(1:4)/TCAN/TSNO/TPND
       0.2       0.2       0.2       0.2       0.0       0.0       0.0       0.0       0.0  !> THLQ(1:4)/THIC(1:4)/ZPND
6 values would be required had NRSOILAYEREADFLAG been activated with option 1.

Inside the code, the attributes of the last-assigned layer (in this case, layer 4) are assigned to all lower layers:

do j = 5, NSL
  sand(:, j) = sand(:, 4)
  clay(:, j) = clay(:, 4)
  orgm(:, j) = orgm(:, 4)
  tbar(:, j) = tbar(:, 4)
  thlq(:, j) = thlq(:, 4)
  thic(:, j) = thic(:, 4)
end do

Verifying the state of NRSOILAYEREADFLAG

The following only applies if CLASS is activated as the HLSS in the model. The following information is not printed for runs using SVS as the HLSS.

The state of NRSOILAYEREADFLAG can be inferred from the CLASS prognostic state summary printed to MESH_output_echo_print.txt at the end of a normal simulation.

If NRSOILAYEREADFLAG is disabled or if only 3 layers are defined in MESH_input_soil_layers.txt, only three values for the respective fields are printed to the file:

MESH_output_echo_print.txt (excerpt)
    1.770     1.913    2.122     0.000   -0.011     0.723  !> TBAR(1:3)/TCAN/TSNO/TPND
    0.444     0.447    0.447     0.028    0.000     0.392     0.095  !>THLQ(1:3)/THIC(1:3)/ZPND
    0.000     0.000  151.256     0.840  893.673     0.000  !>RCAN/SNCAN/SNO/ALBS/RHOS/GRO

If NRSOILAYEREADFLAG is activated with option 1, and 4 layers are defined in MESH_input_soil_levels.txt, four values for the respective fields are printed to the file:

MESH_output_echo_print.txt (excerpt)
    2.585     4.023    4.165     5.566    0.000     0.000     0.000  !>TBAR(1:4)/TCAN/TSNO/TPND
    0.117     0.139    0.042     0.342    0.000     0.000     0.000     0.000     0.000  !>THLQ(1:4)/THIC(1:4)/ZPND
    0.000     0.000    0.192     0.685  286.956     1.000  !> RCAN/SNCAN/SNO/ALBS/RHOS/GRO

If NRSOILAYEREADFLAG is activated with option <n> set to 4, and 6 layers are defined in MESH_input_soil_levels.txt, only four values for the respective fields are printed to the file:

MESH_output_echo_print.txt (excerpt)
    2.585     4.023    4.165     5.566    0.000     0.000     0.000  !>TBAR(1:4)/TCAN/TSNO/TPND
    0.117     0.139    0.042     0.342    0.000     0.000     0.000     0.000     0.000  !>THLQ(1:4)/THIC(1:4)/ZPND
    0.000     0.000    0.192     0.685  286.956     1.000  !> RCAN/SNCAN/SNO/ALBS/RHOS/GRO

Considerations

Decreasing the number of soil layers in an existing setup with "NRSOILAYEREADFLAG 1"

If the soil layers defined in MESH_input_soil_layers.txt is changed to decrease the number of soil layers in an existing setup where NRSOILAYEREADFLAG was previously activated with option 1, all soil-related parameters and initial values must also be updated in MESH_parameters_CLASS.ini or MESH_parameters.txt.

If previously, MESH_input_soil_levels.txt defined 4 layers and is changed to define only 3 layers, but the input parameter file is not updated when NRSOILAYEREADFLAG is already activated with option 1, the following file may cause unexpected behaviour:

MESH_parameters_CLASS.ini (excerpt)
      70.0      70.0      70.0      70.0  !> SAND(1:4)
      30.0      30.0      30.0      30.0  !> CLAY(1:4)
       0.0       0.0       0.0       0.0  !> ORGM(1:4)
       5.0       5.0       5.0       5.0       5.0       0.0       5.0  !> TBAR(1:4)/TCAN/TSNO/TPND
       0.2       0.2       0.2       0.2       0.0       0.0       0.0       0.0       0.0  !> THLQ(1:4)/THIC(1:4)/ZPND
  • The values read for SAND, CLAY, and ORGM are not impacted because no parameters follow them in the line. The last values (in the fourth column) for each of these fields is ignored.
  • TBAR is not impacted because it leads the line, and the expected three values are read as before.
  • TCAN is not impacted, only because it was the same value as TBAR(4) before. The value read (previously from the fifth column, now from the fourth column) is still "5.0".
  • TSNO is erroneously read as "5.0" (in the fifth column), which could adversly impact snow dynamics is snow mass (SNO) exists in the first time-step of the run.
  • TPND was previously assigned a value of "5.0", but is now assigned a value of "0.0" (in the sixth column).
  • THLQ is not impacted because it leads the line, and the expected three values are read as before.
  • THIC is erroneously assigned a vlaue of "0.2" in the first soil layer (formerly the value of THLQ(4), leftover from when the file was read for 4 layers), which could cause unexpected behaviour when previously no ice content was expected to occur in the soil.
  • ZPND is not impacted, only because value read now (previously from the ninth column, now from the seventh column) is still "0.0".

To be read correctly, the file should be revised to remove the leftover values and specify values for all soil-related fields for only 3 layers:

MESH_parameters_CLASS.ini (excerpt)
      70.0      70.0      70.0  !> SAND(1:3)
      30.0      30.0      30.0  !> CLAY(1:3)
       0.0       0.0       0.0  !> ORGM(1:3)
       5.0       5.0       5.0       5.0       0.0       5.0  !> TBAR(1:3)/TCAN/TSNO/TPND
       0.2       0.2       0.2       0.0       0.0       0.0       0.0  !> THLQ(1:3)/THIC(1:3)/ZPND

Increasing the number of soil layers in an existing setup with "NRSOILAYEREADFLAG 1"

If the soil layers defined in MESH_input_soil_layers.txt is changed to increase the number of soil layers in an existing setup where NRSOILAYEREADFLAG was previously activated with option 1, all soil-related parameters and initial values must also be updated in MESH_parameters_CLASS.ini or MESH_parameters.txt.

If previously, MESH_input_soil_levels.txt defined 3 layers and is changed to define 4 layers, but the input parameter file is not updated when NRSOILAYEREADFLAG is already activated with option 1, the following file will cause the model to exit with an error while reading values from the file:

MESH_parameters_CLASS.ini (excerpt)
      70.0      70.0      70.0  !> SAND(1:3)
      30.0      30.0      30.0  !> CLAY(1:3)
       0.0       0.0       0.0  !> ORGM(1:3)
       5.0       5.0       5.0       5.0       0.0       5.0  !> TBAR(1:3)/TCAN/TSNO/TPND
       0.2       0.2       0.2       0.0       0.0       0.0       0.0  !> THLQ(1:3)/THIC(1:3)/ZPND

The model will stop with the following error:

Older code may simply exit with a Fortran exception:

In this case, the comments in the file were read when trying to read a fourth value for SAND(4), which could not be parsed as a number:

MESH_parameters_CLASS.ini (excerpt)
      70.0      70.0      70.0  !> SAND(1:3)
Some version of MESH will strip comments from the line when reading the file, and would intead continue to read the next line the in file – which would also lead to unexpected behaviour. This behaviour is equivalent to the behaviour described immediately below.

If the comments did not exist, it would actually cascade to the next line and read the value meant for CLAY(1) as the fourth value for SAND(4), which could result in unexpected behaviour:

MESH_parameters_CLASS.ini (excerpt)
      70.0      70.0      70.0
      30.0      30.0      30.0
       0.0       0.0       0.0
       5.0       5.0       5.0       5.0       0.0       5.0
       0.2       0.2       0.2       0.0       0.0       0.0       0.0
  • SAND(1:3) are read as before (from the first three columns of the first line).
  • SAND(4) is now read as "30.0" (from the first column in the second line).
  • CLAY(1:2) are read as "30.0" and "30.0" respectively (from the second and third columns in the second line), which only coincidentally match the expected values.
  • CLAY(3:4) are read as "0.0" and "0.0" (from the first two columns in the next line), which could cause unexpected behaviour if values > 0.0 were expected.

This cascade would continue until no more numbers could be read from the file, when the model would again stop with a 'read'-related error.

Related pages

  • Page:
    MESH_input_soil_levels.txt — MESH_input_soil_levels.txt describes the depth in meters of connected soil layers in the soil profile. It is similar to the Soil_3lev file used by the CLASS Stand-Alone Driver. The first layer is the surface layer, which can be no less than 10 cm in depth. A minimum of three soil layers are required in the file.

  • No labels