Consistent naming everywhere in the model source codes

[SarahAlidoost]

Currently code includes some structures/variables with different names although their values are the same like SoilProperties and SoilVariables, or SoilVariables.POR and SoilProperties.porosity. After fixing issue #82, this issue can be addressed. See more examples:

    Genuchten.Theta_s = SoilProperties.SaturatedMC;
    Genuchten.Theta_r = SoilProperties.ResidualMC;
    Genuchten.Theta_f = SoilProperties.fieldMC;
    Genuchten.Alpha = SoilProperties.Coefficient_Alpha;
    Genuchten.n = SoilProperties.Coefficient_n;

More examples where names are not consistent:

POR  vs porosity
Ks  vs SaturatedK

[yijianzeng]

Hi @SarahAlidoost I strongly suggest adding Van, so VanGenuchten.Theta_s = SoilProperties.SaturatedMC; VanGenuchten.Theta_r = SoilProperties.ResidualMC; VanGenuchten.Theta_f = SoilProperties.fieldMC; VanGenuchten.Alpha = SoilProperties.Coefficient_Alpha; VanGenuchten.n = SoilProperties.Coefficient_n;

In the community, people are calling this VG model, but in case 'VG' is too short as suggested by "Matlab coding style", then we should use VanGenuchten. In ISMC, we also have the "VanGenuchten" award.

[SarahAlidoost]

Hi @SarahAlidoost I strongly suggest adding Van, so VanGenuchten.Theta_s = SoilProperties.SaturatedMC; VanGenuchten.Theta_r = SoilProperties.ResidualMC; VanGenuchten.Theta_f = SoilProperties.fieldMC; VanGenuchten.Alpha = SoilProperties.Coefficient_Alpha; VanGenuchten.n = SoilProperties.Coefficient_n;

In the community, people are calling this VG model, but in case 'VG' is too short as suggested by "Matlab coding style", then we should use VanGenuchten. In ISMC, we also have the "VanGenuchten" award.

Thanks. I replaced Genuchten with VanGenuchten in this pull request . There, I also asked for your review of the code structure and variable names.

However, this implementation does not fix this issue. Creating a lookup table for all variables with their definitions can help to address this issue. In this way, when someone wants to contribute/fix the code, they use the same variable name everywhere in the code. Any other ideas on how to fix this issue?

[yijianzeng]

However, this implementation does not fix this issue. Creating a lookup table for all variables with their definitions can help to address this issue. In this way, when someone wants to contribute/fix the code, they use the same variable name everywhere in the code. Any other ideas on how to fix this issue?

Hi Sarah, there are two concepts in this concept:

1. basic physical SoilProperties, which usually include soil texture, bulk density, saturated hydraulic conductivity, soil organic content, and porosity;
2. and then based on the above basic soil physical properties, we can derive soil hydraulic and thermal properties. For Hydraulic properties (soil water retention curve - SWRC, and hydraulic conductivity curve), people usually used VanGenuchten model, but there are many other models used to describe SWRC and hydraulic conductivity curve. We can have a selection of models for describing hydraulic properties (for example, Brooks-Corey, Fredlund–Xing, Groenevelt–Grant, Ippisch–Vogel–Bastian, 1999 Kosugi, just to name a few). Here is a good review literature as below:

Du, C. Comparison of the performance of 22 models describing soil water retention curves from saturation to oven dryness. Vadose Zone J. 2020; 19:e20072. https://doi.org/10.1002/vzj2.20072

3. similarly, for thermal properties, there are also various models to describe heat capacity and thermal conductivity. See below reference

He, H., He, D., Jin, J., Smits, K. M., Dyck, M., Wu, Q., Si, B. and Lv, J.: Room for improvement: A review and evaluation of 24 soil thermal conductivity parameterization schemes commonly used in land-surface, hydrological, and soil-vegetation-atmosphere transfer models, Earth-Science Rev., 211, 103419, doi:10.1016/J.EARSCIREV.2020.103419, 2020.

[yijianzeng]

@SarahAlidoost Hi Sarah, I'd made a logic chart (see below) of those subroutines linked to 'SoilProperties' 'SoilVariables'etc. i think the look up table to explain each variables for the whole STEMMUS-SCOPE could be less traceable than preparing a document in a 'readthedoc' template. If the 'readthedoc' is prepared as such for STEMMUS-SCOPE, we can then further fine-tune and unify the variables from there, since the 'logic chart' as i showed in the document, could be realized via the template of 'readthedoc'?

Please also see attached some references/explanations (prepared by Lianyu) for certain lines in those relevant subroutines you created. Could you help add them into the code?

Please find the document as below (please let me know if you have access to this doc or not.): https://universiteittwente-my.sharepoint.com/:w:/g/personal/y_zeng_utwente_nl/EUCd08cFYoRKljt8llK1RCUBS1Ep7Q1dy3HQyTMIydN0qA

[yijianzeng]

Just in case the above shared document is not accessible, i also copied them here as below:

applySoilHeteroEffect.m L25: % (van Genuchten 1980, Soil Sci Soc Am J.) L50: % Eqlspace=0 means the thickness of soil layer is of the same along the vertical direction (i.e., equal space/distance). The initial state variables (h, T, TT) and index of soil type were set as one constant value here.

calcInitH.m L2: %{ Calculate soil water potential (initH) using van Genuchten model. van Genuchten, M.T. (1980), A Closed-form Equation for Predicting the Hydraulic Conductivity of Unsaturated Soils. Soil Science Society of America Journal, 44: 892-898. https://doi.org/10.2136/sssaj1980.03615995004400050002x %}

calcLambda.m L2: %{ Calculate soil hydraulic properties according to: Cosby, B. J., Hornberger, G. M., Clapp, R. B., and Ginn, T. R. (1984), A Statistical Exploration of the Relationships of Soil Moisture Characteristics to the Physical Properties of Soils, Water Resour. Res., 20( 6), 682– 690, doi:10.1029/WR020i006p00682. %}

calcPhi_s.m L2: %{ Calculate soil hydraulic properties according to: Cosby, B. J., Hornberger, G. M., Clapp, R. B., and Ginn, T. R. (1984), A Statistical Exploration of the Relationships of Soil Moisture Characteristics to the Physical Properties of Soils, Water Resour. Res., 20( 6), 682– 690, doi:10.1029/WR020i006p00682. %}

calculateInitialThermal.m L29: % (de Vries, 1963, Physics of Plant Environment) L60: % (Johansen, 1975, Thermal conductivity of soils) L77: % simplified de Vries method (Tian et al., 2016, Eur. J. Soil Sci.) L99: % Farouki thermal parameter method (Farouki, 1981, Cold Regions Sci. Tech.)

setSoilConstants.m L8-14 SoilConstants.Vol_qtz = FOS; % fraction of soil sand SoilConstants.VPERSOC = equations.calc_msoc_fraction(MSOC); % fraction of soil organic matter SoilConstants.FOSL = 1 - FOC - FOS - SoilConstants.VPERSOC; % fraction of soil silt SoilConstants.Phi_S = [-17.9 -17 -17 -19 -10 -10]; % parameter for soil water retention curve of Clapp & Hornberger (1978) SoilConstants.Phi_soc = -0.0103; % parameter for soil water retention curve of Clapp & Hornberger (1978) SoilConstants.Lamda_soc = 2.7; % parameter for soil water retention curve of Clapp & Hornberger (1978) SoilConstants.Theta_soc = 0.6; % parameter for soil water retention curve of Clapp & Hornberger (1978)

updateBtmh.m L3: % VG soil water retention model (van Genuchten 1980, Soil Science Society of America Journal)

updateHfreez.m L2: %{ Update soil freezing potential. Yu, L., Zeng, Y., Wen, J., & Su, Z. (2018). Liquid-Vapor-Air Flow in the Frozen Soil. Journal of Geophysical Research: Atmospheres, 123(14), 7393-7415. doi:10.1029/2018JD028502. %}

updateInitH.m L2: %{ Update intial soil water potential using van Genuchten (VG) and Clapp & Hornberger (CH) methods. van Genuchten, M. T. (1980). A Closed-form Equation for Predicting the Hydraulic Conductivity of Unsaturated Soils. Soil Sci. Soc. Am. J., 44(5), 892-898. doi:10.2136/sssaj1980.03615995004400050002x. Clapp, R. B., & Hornberger, G. M. (1978). Empirical equations for some soil hydraulic properties. Water Resour. Res., 14(4), 601-604. doi:10.1029/WR014i004p00601. Yu, L., Zeng, Y., Wen, J., & Su, Z. (2018). Liquid-Vapor-Air Flow in the Frozen Soil. Journal of Geophysical Research: Atmospheres, 123(14), 7393-7415. doi:10.1029/2018JD028502. %}

L16: % VG soil water retention model

L18: % CH soil water retention model

UpdateSoilVariables.m L24: % TODO check undefined Theta_s_ch; Theta_s_ch=[0.5 0.45 0.41 0.43 0.41 0.41];

CondL_h.m L2: %{ Update soil water content and hydraulic conductivity. [1] Yijian Zeng & Zhongbo Su (2013a): STEMMUS (Simultaneous Transfer of Energy, Mass and Momentum in Unsaturated Soil): Department of Water Resources, ITC Faculty of Geo-Information Science and Earth Observation, University of Twente ISBN: 978–90–6164–351–7 [2] Zeng, Y., & Su, Z. (2013b). Reply to comment by Binayak P. Mohanty and Zhenlei Yang on "A simulation analysis of the advective effect on evaporation using a two-phase heat and mass flow model''. Water Resources Research, 49(11), 7836-7840. doi:10.1002/2013wr013764 [3] Tuller, M., and D. Or (2005), Water films and scaling of soil characteristic curves at low water contents, Water Resour. Res., 41, W09403, doi:10.1029/2005WR004142. [4] Lebeau, M., and Konrad, J.-M. (2010), A new capillary and thin film flow model for predicting the hydraulic conductivity of unsaturated porous media, Water Resour. Res., 46, W12554, doi:10.1029/2010WR009092. [5] Zhang, Z. F. (2011), Soil water retention and relative permeability for conditions from oven-dry to full saturation, Vadose Zone J., 10, 1299–1308. [6] Yu, L., Zeng, Y., Wen, J., & Su, Z. (2018). Liquid-Vapor-Air Flow in the Frozen Soil. Journal of Geophysical Research: Atmospheres, 123(14), 7393-7415. doi:10.1029/2018JD028502. %} L47: % consider the film flow effect, (Zhang, 2011, Vadose Zone J.)

L116-189: Commented

L298-300: FILM=1; % indicator for film flow parameterization; % =1, (Zhang, 2011, Vadose Zone J.; Zeng et al., 2013b, Water Resour. Res.); % =2, (Lebeau and Konrad, 2010, Water Resour. Res.) L302: % %%%%%%%%% see (Zhang, 2011, Vadose Zone J.; Zeng et al., 2013b, Water Resour. Res.) L329: %%%%%%%%% see (Lebeau and Konrad, 2010, Water Resour. Res.) L338-339: SWM=0.1; %THE SATURATION WHEN SURFACE ROUGHNESS OF THE SOLID GRAIN BECOMES NEGNIGIBLE (-) IT IS EQUIVALENT TO % SATURATION BEEN 1000M FROM (TULLER AND OR, 2005, Water Resour. Res.)