Refactor and move all cond*_ functions

[SarahAlidoost]

No description provided.

[SarahAlidoost]

@yijianzeng For each function below, please add one line explanation and suggest a better name in this issue, thanks

• Condg_k_g
• CondL_h
• CondL_T
• CondL_Tdisp
• CondT_coeff
• CondV_DE
• CondV_DVg

[yijianzeng]

• Condg_k_g ----> gasConductivity
  This is to calculate the intrinsic permeability of soil for gas flow.

Ref: Scanlon, B. R. (2000), Soil gas movement in unsaturated systems, in Handbook of Soil Science, edited by M. E. Sumner, pp. A277– A319, CRC Press, Boca Raton, Fla.

Zeng, Y., Su, Z., Wan, L. and Wen, J.: Numerical analysis of air-water-heat flow in unsaturated soil: Is it necessary to consider airflow in land surface models?, J. Geophys. Res. Atmos., 116(D20), 20107, doi:10.1029/2011JD015835, 2011.

• CondL_h -------> hydraulicConductivity
  This is to calculate the hydraulic conductivity of soil, based on hydraulic conductivity models (like VG and others).

van Genuchten, M. T. (1980), A closed-form equation for predicting the hydraulic conductivity of unsaturated soils, Soil Sci. Soc. Am. J., 44, 892–898
Zeng, Y., Su, Z., Wan, L. and Wen, J.: Numerical analysis of air-water-heat flow in unsaturated soil: Is it necessary to consider airflow in land surface models?, J. Geophys. Res. Atmos., 116(D20), 20107, doi:10.1029/2011JD015835, 2011.

• CondL_T -------> thermalHydraulicConductivity
  This is to calculate the thermal-hydraulic conductivity, considering the temperature dependence of matric pressure.

Ref: Saito, H., J. Šimůnek, and B. P. Mohanty (2006), Numerical analysis of coupled water, vapor, and heat transport in the vadose zone, Vadose Zone J., 5(2), 784– 800.
Zeng, Y., Su, Z., Wan, L. and Wen, J.: Numerical analysis of air-water-heat flow in unsaturated soil: Is it necessary to consider airflow in land surface models?, J. Geophys. Res. Atmos., 116(D20), 20107, doi:10.1029/2011JD015835, 2011.

• CondL_Tdisp ---> transportCoefficientAbsorbedLiquidFlow
  This is to calculate the transport coefficient for absorbed liquid flow due to temperature gradient.
  Ref: Groenevelt, P. H., and B. D. Kay (1974), On the interaction of water and heat transport in frozen and unfrozen soils: II. The liquid phase, Soil Sci. Soc. Am. Proc., 38, 400– 404,
  Zeng, Y., Su, Z., Wan, L. and Wen, J.: Numerical analysis of air-water-heat flow in unsaturated soil: Is it necessary to consider airflow in land surface models?, J. Geophys. Res. Atmos., 116(D20), 20107, doi:10.1029/2011JD015835, 2011.

• CondT_coeff ---> thermalConductivityCapacity
  This is to calculate thermal conductivity and thermal capacity.

Ref: Chung, S. O., and R. Horton (1987), Soil heat and water flow with a partial surface mulch, Water Resour. Res., 23(12), 2175– 2186,
Zeng, Y., Su, Z., Wan, L. and Wen, J.: Numerical analysis of air-water-heat flow in unsaturated soil: Is it necessary to consider airflow in land surface models?, J. Geophys. Res. Atmos., 116(D20), 20107, doi:10.1029/2011JD015835, 2011.

• CondV_DE -----> vaporDiffusivityDispersivityEnhancement
  This is to calculate vapor diffusivity, vapor dispersivity, and vapor enhancement factor.

Zeng, Y., Su, Z., Wan, L. and Wen, J.: Numerical analysis of air-water-heat flow in unsaturated soil: Is it necessary to consider airflow in land surface models?, J. Geophys. Res. Atmos., 116(D20), 20107, doi:10.1029/2011JD015835, 2011.

Yu, L., Zeng, Y. and Su, Z.: STEMMUS-UEB v1.0.0: integrated modeling of snowpack and soil water and energy transfer with three complexity levels of soil physical processes, Geosci. Model Dev, 14, 7345–7376, doi:10.5194/gmd-14-7345-2021, 2021.

• CondV_DVg ----> gasLongitudinalDispersivity
  This is to calculate the gas phase longitudinal dispersivity.
  Zeng, Y., Su, Z., Wan, L. and Wen, J.: Numerical analysis of air-water-heat flow in unsaturated soil: Is it necessary to consider airflow in land surface models?, J. Geophys. Res. Atmos., 116(D20), 20107, doi:10.1029/2011JD015835, 2011.

[SarahAlidoost]

@yijianzeng While refactoringCond*_ functions, I found major issues, see below. Please help to address them:

1. The *_flm variables are calculated here. But they are not used in STEMMUS_SCOPE. Is this correct? Note that in refactoring work, this code block is deleted entirely.
2. in CondL_h, Variables Phi_s, and Lamda are used for calculating other variables. However, they are empty vectors. Is this correct?
3. at this code block, first, Theta_II(ML, ND) is calculated. Then it is used to calculate Theta_LL(ML, ND). Later, again Theta_LL(ML, ND) is used to calculate Theta_II(ML, ND), see here. This is a case of "circular" calculation that might be an error. Can you check this?
4. In the comment above, you explained that "CondL_T script calculates the thermal-hydraulic conductivity, considering the temperature dependence of matric pressure.". However, CondL_T contains no useful code. Is this correct?
5. The variable f0 is calculated in CondV_DVg. However, this variable is not used by the rest of the code. Is this correct?
6. can you suggest a better name and reference for EfeCapCond?
7. There are two equations used to calculate DTheta_UUh. Those two equations are equal except that Theta_s(J) - Theta_r(J) is used here whereas Theta_m(ML) - Theta_r(J) is used here. The same issue happened for variable DTheta_LLh, Theta_s(J) - Theta_r(J) is used here whereas Theta_m(ML) - Theta_r(J) is used here . Are those equations using Theta_s and Theta_m correct?

[SarahAlidoost]

@yijianzeng please have a look at the questions above.

[yijianzeng]

1. The *_flm variables are calculated here. But they are not used in STEMMUS_SCOPE. Is this correct? Note that in refactoring work, this code block is deleted entirely.

Hi, Sarah, this film flow can improve the numerical convergence, since this is linked to soil water characteristic curve. Although it is not used in the current STEMMUS-SCOPE, this is an important part to account for freezing/thawing, which is to be activated later on.

[yijianzeng]

2. in CondL_h, Variables Phi_s, and Lamda are used for calculating other variables. However, they are empty vectors. Is this correct?

Hi Sarah, 'Phi_s' and 'Lamda' are parameters used by Clapp-Hornberger soil hydraulic model, see (Yu, Zeng, et al. JGR 2018). Although in STEMMUS-SCOPE, we used VG model, it is still making sense to keep Clapp-Hornberger model for future applications.

[yijianzeng]

3. at this code block, first, Theta_II(ML, ND) is calculated. Then it is used to calculate Theta_LL(ML, ND). Later, again Theta_LL(ML, ND) is used to calculate Theta_II(ML, ND), see here. This is a case of "circular" calculation that might be an error. Can you check this?

Hi Sarah, 'Theta_II' is soil ice content, and 'Theta_LL' is liquid water content, 'Theta_UU' is the total water content before soil freezing. The 'Theta_UU' is set as saturation. This is also linked to (Yu, Zeng, et al. JGR 2018).

[yijianzeng]

4. In the comment above, you explained that "CondL_T script calculates the thermal-hydraulic conductivity, considering the temperature dependence of matric pressure.". However, CondL_T contains no useful code. Is this correct?

It is indeed currently not used (e.g., mute the temperature dependence), but we should keep it for future extensions.

[yijianzeng]

5. The variable f0 is calculated in CondV_DVg. However, this variable is not used by the rest of the code. Is this correct?

'f0' is the Tortuosity factor, it is used in 'CondV_E' see here. It would make sense to refactor it into a function.

[yijianzeng]

6. can you suggest a better name and reference for EfeCapCond?

This is used to calculate Heat Capacity and Thermal Conductivity. Perhaps renamed as 'SoilThermalProperites'.

[yijianzeng]

7. There are two equations used to calculate DTheta_UUh. Those two equations are equal except that Theta_s(J) - Theta_r(J) is used here whereas Theta_m(ML) - Theta_r(J) is used here. The same issue happened for variable DTheta_LLh, Theta_s(J) - Theta_r(J) is used here whereas Theta_m(ML) - Theta_r(J) is used here . Are those equations using Theta_s and Theta_m correct?

Hi Sarah, this is used by Lianyu to account for extremely dry condition, it is ok to keep them.

[SarahAlidoost]

3. at this code block, first, Theta_II(ML, ND) is calculated. Then it is used to calculate Theta_LL(ML, ND). Later, again Theta_LL(ML, ND) is used to calculate Theta_II(ML, ND), see here. This is a case of "circular" calculation that might be an error. Can you check this?

Hi Sarah, 'Theta_II' is soil ice content, and 'Theta_LL' is liquid water content, 'Theta_UU' is the total water content before soil freezing. The 'Theta_UU' is set as saturation. This is also linked to (Yu, Zeng, et al. JGR 2018).

Hi Yijian, the issue here is the circular calculation. Do you mean this procedure is correct?

[SarahAlidoost]

7. There are two equations used to calculate DTheta_UUh. Those two equations are equal except that Theta_s(J) - Theta_r(J) is used here whereas Theta_m(ML) - Theta_r(J) is used here. The same issue happened for variable DTheta_LLh, Theta_s(J) - Theta_r(J) is used here whereas Theta_m(ML) - Theta_r(J) is used here . Are those equations using Theta_s and Theta_m correct?

Hi Sarah, this is used by Lianyu to account for extremely dry condition, it is ok to keep them.

The issue here is that those equations are exactly the same except for using Theta_s or Theta_m . Do you mean those equations are correct?

[yijianzeng]

3. at this code block, first, Theta_II(ML, ND) is calculated. Then it is used to calculate Theta_LL(ML, ND). Later, again Theta_LL(ML, ND) is used to calculate Theta_II(ML, ND), see here. This is a case of "circular" calculation that might be an error. Can you check this?

Hi Sarah, 'Theta_II' is soil ice content, and 'Theta_LL' is liquid water content, 'Theta_UU' is the total water content before soil freezing. The 'Theta_UU' is set as saturation. This is also linked to (Yu, Zeng, et al. JGR 2018).

Hi Yijian, the issue here is the circular calculation. Do you mean this procedure is correct?

Hi Sarah, this procedure is correct in my check of this code block. The main confusion could come from many conditional statements. But the physics it represents reads fine to me.

[yijianzeng]

7. There are two equations used to calculate DTheta_UUh. Those two equations are equal except that Theta_s(J) - Theta_r(J) is used here whereas Theta_m(ML) - Theta_r(J) is used here. The same issue happened for variable DTheta_LLh, Theta_s(J) - Theta_r(J) is used here whereas Theta_m(ML) - Theta_r(J) is used here . Are those equations using Theta_s and Theta_m correct?

Hi Sarah, this is used by Lianyu to account for extremely dry condition, it is ok to keep them.

The issue here is that those equations are exactly the same except for using Theta_s or Theta_m . Do you mean those equations are correct?

Yes Sarah, these equations are physically meaningful, it is used to account for extremely dry condition, and expect to improve numerical convergency.