Mapping of internal model variables and parameters to standard names

[verseve]

Feature type

Changing existing functionality

Improvement Description

The mapping of model variables to external names (e.g. in the TOM config file and BMI) is one to one. For example, the satwaterdepth variable of the vertical SBM concept can be accessed in Julia through model.vertical.satwaterdepth, and should be mapped to vertical.satwaterdepth in the TOML config file to write this variable as output or read as a state input. As part of v1.0, the large structs of vertical concepts are divided into sub-models/structs. For example the SBM concept is divided into interception, snow, glacier and soil modules. Additionally, separate structs are used for model variables and parameters, and we make use of shared parameters (e.g. for vegetation).

As a consequence, this results in a mapping that can get complex for an end-user, with below an example for a part of the TOML config file:

[output.vertical.interception.variables]
canopy_storage = "canopystorage"

[output.vertical.soil.variables]
satwaterdepth = "satwaterdepth"
tsoil = "tsoil"
ustorelayerdepth = "ustorelayerdepth"

[output.vertical.snow.variables]
snow_storage = "snow"
snow_water = "snowwater"

Additionally, a disadvantage of the one to one mapping is that any change in the setup of the Model struct requires also a change in the TOML config file. An improvement would be to work with standard variable/parameter names resulting in a more user friendly external access of model variables.

Implementation Description

For the variable names CSDMS provides a good standard that we can use: https://csdms.colorado.edu/wiki/CSDMS_Standard_Names.

Below an example of (part of) the TOML file using external names from the CSDMS standard:

[input.static]
soil_water__saturated_volume_fraction = "thetaS"
soil_water__residual_volume_fraction = "thetaR"

vegetation_woody-part__storage_capacity = "Swood"
vegetation__leaf-area_index = "LAI"
vegetation_canopy__light-extinction_coefficient = "Kext"

snowpack__degree-day_coefficient = "Cfmax"

channel_water_flow__manning_n_parameter = "N"

land_surface__slope = "Slope"

[output.variables]
soil_water_sat-zone_top__depth = "zi"
soil_water__infiltration_volume_flux = "actinfilt"
soil_surface__temperature = "tsoil"
soil_water_sat-zone__depth = "satwaterdepth"
soil_water_unsat-zone__depth-per-soil_layer = "ustorelayerdepth"

vegetation_canopy_water__storage = "canopystorage"

channel_water__volume_flow_rate = "q_river"
channel_water__time_average_of_volume_flow_rate = "q_av_river"

subsurface_water__volume_flow_rate = "ssf"

Additional Context

No response

[PeterNelemans]

A small additional note on g_tt: according to the current docs, this parameter is the threshold temperature for snowfall above glacier. This would also make sense, given that tt is the threshold temperature for snowfall. However, g_tt is actually the threshold temperature for glacier melt, so the description in the current docs is incorrect. This has been fixed in the new docs. Thanks @JoostBuitink!

However, it would also make sense to rename g_tt to g_ttm, since ttm is the threshold temperature for snowmelt.