STEMMUS_SCOPE BMI: which variables to expose

[BSchilperoort]

In #208 and EcoExtreML/STEMMUS_SCOPE_Processing#89 I have implemented a BMI for STEMMUS_SCOPE.

For testing purposes I have exposed two variables: the output variable fluxes.Resp and input+output variable TT (soil temperature).

For the implementation of the full BMI we will need to know which variables we want to expose. For these variables we will also need a long or standard name, as well as their unit.

Variables can be an "input variable" an "output variable" or both.

Variable standard name	Variable name in code	Input/output?	Unit	Grid
vegetation_respiration	fluxes.Resp	out	?	none
soil_temperature	TT	in+out	degC	ModelSettings.mN

@yijianzeng @bobzsu @Yunfei-Wang1993 could you fill in this table for all variables that need to be exposed?

[SarahAlidoost]

@MostafaGomaa93 please see the comment above. Which variables do you need to couple STEMMUS_SCOPE to the groundwater model (MODFLOW 6), please add them to the table above, thanks. relates #205

[MostafaGomaa93]

@SarahAlidoost. thanks. I am still not yet familiar with the variable names in the code, but I tried my best above. @yijianzeng can confirm the variables I add.

Variable standard name	Variable name in code	Input/output?	Unit	Grid
Sum of liquid and vapor water fluxes	sum of (QL, Qv, Qa)	out	kg/m2/s	none
Specified matric head at the deepest sublayer (Groundwater head)	hN (used when BoundaryCondition.NBChB == 1)	in	m	none

[BSchilperoort]

Hi @MostafaGomaa93, I've moved the variables you added to your own comment.

By grid I mean if they are on a certain model grid (for example the soil layers, or fluorescent wavelengths). I think the variables you specify are not on a specific model grid (if they are just one value, not an array).

[MostafaGomaa93]

Hi @BSchilperoort, thanks for your update. Sorry for my misunderstanding of what it means by "Grid". I think indeed the variables I add are one value, not an array.

[yijianzeng]

Variable standard name (refers to ALMA)	Variable name in code	variable name in equation (add also a link to paper)	Input/output?	Unit	Grid
vegetation_respiration	fluxes.Resp		out	?	none
soil_temperature	TT		in+out	degC	ModelSettings.mN
SoilVariables.hh	'hh'		in+out	mH2O	ModelSettings.mN+KT
not_availalbe (leaf water potential)	'PSI'		in+out	mH2O(need to check)	ModelSettings.mN+KT

Before i continue further, these two important soil-plant state varables (soil matric water potential and leaf water potential) are not output with time dimensions?

@Yunfei-Wang1993

[MostafaGomaa93]

Here are the variables needed for groundwater coupling (implemented in the SSM_v.0.3.2 branch)

Variable standard name	Variable name in code	Input/output?	Unit in STEMMUS	Grid	Unit in MODFLOW
Groundwater level	GroundwaterSettings.headBotmLayer	in	cm	none	m
Groundwater temperature	GroundwaterSettings.tempBotm	in	degC	none	degC
Elevation of top surface level	GroundwaterSettings.toplevel	in	cm	none	m
Groundwater recharge	gwfluxes.recharge	out	cm/s	none	m/day
Evaporation	EVAP	out	cm/s	none	m/day
Transpiration	Trap	out	cm/s	none	m/day
Soil water root uptake	RWUs	out	cm/s	none	m/day
Groundwater root uptake	RWUg	out	cm/s	none	m/day
Dunnian runoff	ForcingData.R_Dunn	out	cm/s	none	m/day
Hortonian runoff	ForcingData.R_Hort	out	cm/s	none	m/day
Total runoff	RS	out	cm/s	none	m/day

For the variables (gwfluxes.recharge, EVAP, RWUs, RWUg, R_Dunn, R_Hort, RS), aggregation from STEMMUS time step (30 mins) to MODFLOW time step (1 day) is needed in the BMI.

For the gwfluxes.recharge, change sign (positive to negative and vice versa) is needed in the BMI.

For the variables (GroundwaterSettings.headBotmLayer, GroundwaterSettings.tempBotm), interpolation is needed in the BMI

The following table shows variables needed for further analysis and post-processing, but may not be passed to MODFLOW.

Variable standard name	Variable name in code	Input/output?	Unit in STEMMUS	Grid
Precipitation	ForcingData.Precip_msr	out	cm/s	none
Applied infiltration	ForcingData.applied_inf	out	cm/s	none
Liquid flux due to matric potential gradient contributed to groundwater recharge	gwfluxes.QLh	in	cm	none
Liquid flux due to temperature gradient contributed to groundwater recharge	gwfluxes.QLT	in	cm	none
Liquid flux due to dry air pressure gradient contributed to groundwater recharge	gwfluxes.QLa	in	cm	none
Vapor flux due to matric potential gradient contributed to groundwater recharge	gwfluxes.QVH	in	cm	none
Vapor flux due to temperature gradient contributed to groundwater recharge	gwfluxes.QVT	in	cm	none
Vapor flux due to dry air pressure gradient contributed to groundwater recharge	gwfluxes.QVa	in	cm	none

[Yunfei-Wang1993]

In #208 and EcoExtreML/STEMMUS_SCOPE_Processing#89 I have implemented a BMI for STEMMUS_SCOPE.

For testing purposes I have exposed two variables: the output variable fluxes.Resp and input+output variable TT (soil temperature).

For the implementation of the full BMI we will need to know which variables we want to expose. For these variables we will also need a long or standard name, as well as their unit.

Variables can be an "input variable" an "output variable" or both.

Variable standard name Variable name in code Input/output? Unit Grid
vegetation_respiration fluxes.Resp out ? none
soil_temperature TT in+out degC ModelSettings.mN
@yijianzeng @bobzsu @Yunfei-Wang1993 could you fill in this table for all variables that need to be exposed?
Hi, Bart, please find the variable table for BMI.
Variable Table_STEMMUS-SCOPE.xlsx

[SarahAlidoost]

@Yunfei-Wang1993 , @DanyangYu , @EntingTang , @Crystal-szj and @yijianzeng Thanks for preparing the variable names. I moved the content of the excel file to a table in this issue, see below. Is this the final version? if so, see the questions:

1. Variables Rli and Rin don't exist in the source code but meteo.Rli, ScopeParameters.Rli, meteo.Rin, ScopeParameters.Rin. Which one should be in the table?
2. Variables Rntot, lEstot, LEctot, Hctot, Hstot, and Gtot should be fluxes.Rntot, fluxes.lEstot, fluxes.LEctot, fluxes.Hctot, fluxes.Hstot, and fluxes.Gtot, right?
3. Variables Tsave and Tcave should be thermal.Tsave and thermal.Tcave, right?
4. What is the standard name of SoilVariables.hh? see the section The carbon budget, in the table.

Variable standard name (refers to ALMA)	Variable name in code	variable name in equation (add also a link to paper)	Input/output?	Unit	Grid
General energy balance components
surface_net_downward_shortwave_flux
Incoming longwave radiation	ScopeParameters.Rli		in	W m-2	none
Incoming shortwave radiation	ScopeParameters.Rin		in	W m-2	none
Net radiation	Rntot		out	W m-2	none
latent heat flux of sunlit leaves	lEch		out	W m-2	none
latent heat flux of shaded leaves	lEcu		out	W m-2	none
latent heat flux of soil	lEstot		out	W m-2	none
latent heat flux of canopy	LEctot		out	W m-2	none
sensible heat flux of sunlit leaves	Hch		out	W m-2	none
sensible heat flux of shaded leaves	Hcu		out	W m-2	none
sensible heat of canopy	Hctot		out	W m-2	none
sensible heat flux of soil	Hstot		out	W m-2	none
gound heat flux	Gtot		out	W m-2	none
General water balance components
Precipitation	Precip_msr		in	mm	none
Root water uptake	RWU		out	m2 s-1	none
Surface state variable
soil surface_temperature	thermal.Tsave		out	degC	none
canopy temperature	thermal.Tcave		out	degC	none
Subsurface state variables
mositure_content_of_soil_layer	Theta_UUU		out	m3 m-3	none
Evaporation components
Evaporation	Evap		out	cm s-1	none
Transpiration	Tp_t		out	cm s-1	none
The carbon budget
gross primary production	biochem_out.A		out	umol m-2 s-1	none
gross assimilation rate	Ag		out	umol m-2 s-1	none
soil_respiration	Resp		out	umol m-2 s-1	none
soil_temperature	TT		out	degC	ModelSettings.mN
soil water potential	SoilVariables.hh		out	cm	ModelSettings.mN
leaf water potential	PSI		in+out	m	ModelSettings.mN

[Yunfei-Wang1993]

@Yunfei-Wang1993 , @DanyangYu , @EntingTang , @Crystal-szj and @yijianzeng Thanks for preparing the variable names. I moved the content of the excel file to a table in this issue, see below. Is this the final version? if so, see the questions:

1. Variables Rli and Rin don't exist in the source code but meteo.Rli, ScopeParameters.Rli, meteo.Rin, ScopeParameters.Rin. Which one should be in the table?
2. Variables Rntot, lEstot, LEctot, Hctot, Hstot, and Gtot should be fluxes.Rntot, fluxes.lEstot, fluxes.LEctot, fluxes.Hctot, fluxes.Hstot, and fluxes.Gtot, right?
3. Variables Tsave and Tcave should be thermal.Tsave and thermal.Tcave, right?
4. What is the standard name of SoilVariables.hh? see the section The carbon budget, in the table.

Variable standard name (refers to ALMA) Variable name in code variable name in equation (add also a link to paper) Input/output? Unit Grid
General energy balance components
surface_net_downward_shortwave_flux
Incoming longwave radiation Rli in W m-2 none
Incoming shortwave radiation Rin in W m-2 none
Net radiation Rntot out W m-2 none
latent heat flux of sunlit leaves lEch out W m-2 none
latent heat flux of shaded leaves lEcu out W m-2 none
latent heat flux of soil lEstot out W m-2 none
latent heat flux of canopy LEctot out W m-2 none
sensible heat flux of sunlit leaves Hch out W m-2 none
sensible heat flux of shaded leaves Hcu out W m-2 none
sensible heat of canopy Hctot out W m-2 none
sensible heat flux of soil Hstot out W m-2 none
gound heat flux Gtot out W m-2 none
General water balance components
Precipitation Precip_msr in mm none
Root water uptake RWU out m2 s-1 none
Surface state variable
soil surface_temperature Tsave out degC none
canopy temperature Tcave out degC none
Subsurface state variables
mositure_content_of_soil_layer Theta_UUU out m3 m-3 none
Evaporation components
Evaporation Evap out cm s-1 none
Transpiration Tp_t out cm s-1 none
The carbon budget
gross primary production biochem_out.A out umol m-2 s-1 none
gross assimilation rate Ag out umol m-2 s-1 none
soil_respiration Resp out umol m-2 s-1 none
soil_temperature TT out degC ModelSettings.mN
SoilVariables.hh hh out cm ModelSettings.mN
leaf water potential PSI in+out m ModelSettings.mN

Hi, Sarah, 1: ScopeParameters.Rli and ScopeParameters.Rin should be used here. 2 and 3: You are right. 4: The last three variables we can name them the 'soil and leaf state variables'. SoilVariables.hh means the soil water potential.

[MostafaGomaa93]

Just for the record, the whole SoilVariables structure is exposed to BMI (see here), so we may not need to specify soil_temperature and SoilVariables.hh separately (I leave this decision to @SarahAlidoost).

Evap and RWU are already included in the BMI variables list (here). I already add them.

[SarahAlidoost]

Just for the record, the whole SoilVariables structure is exposed to BMI (see here), so we may not need to specify soil_temperature and SoilVariables.hh separately (I leave this decision to @SarahAlidoost).

@MostafaGomaa93 you are right, the structure SoilVariables is already in STEMMUS_SCOPE_exe.m. However, in BMI get_variable function (python implementation), the variable name in a structure is needed, see examples here. This function does not return the whole structure. Since the standard names are not fully documented in the source code, we use the information in this table.

[MostafaGomaa93]

Three additional values are needed in BMI (according to discussion of issue 237)

Variable standard name	Variable name in code	Input/output?	Unit	Grid
Total soil depth	ModelSettings.Tot_Depth	in	cm	none
Number of soil layers	ModelSettings.NL	in	-	none
Maximum rooting depth	ModelSettings.R_depth	in	cm	none

[SarahAlidoost]

Three additional values are needed in BMI (according to discussion of issue 237)

Variable standard name Variable name in code Input/output? Unit Grid
ModelSettings.Tot_Depth Total soil depth in cm none
ModelSettings.NL Number of soil layers in - none
ModelSettings.R_depth Maximum rooting depth in cm none

thanks for adding these variables. The content of the first two columns should be switched. can you please fix it? also, see my comment.