Standard

class abcmodel.land.standard.StandardLandState(alpha, wg, temp_soil, temp2, surf_temp, wl, wq, wtheta, rs=<factory>, rssoil=<factory>, esat=<factory>, qsat=<factory>, dqsatdT=<factory>, e=<factory>, qsatsurf=<factory>, wCO2=<factory>, cliq=<factory>, temp_soil_tend=<factory>, wgtend=<factory>, wltend=<factory>, le_veg=<factory>, le_liq=<factory>, le_soil=<factory>, le=<factory>, hf=<factory>, gf=<factory>, le_pot=<factory>, le_ref=<factory>, vpd=<factory>)

Bases: AbstractLandState

Standard land surface model state.

alpha: Array

Slope of the light response curve [mol J-1].

wg: Array

Soil moisture content in the root zone [m3 m-3].

temp_soil: Array

Soil temperature [K].

temp2: Array

Deep soil temperature [K].

surf_temp: Array

Surface temperature [K].

wl: Array

No water content in the canopy [m].

wq: Array

Kinematic moisture flux [kg/kg m/s].

wtheta: Array

Kinematic heat flux [K m/s].

rs: Array

Surface resistance [m s-1].

rssoil: Array

Soil resistance [m s-1].

esat: Array

Saturation vapor pressure [Pa].

qsat: Array

Saturation specific humidity [kg/kg].

dqsatdT: Array

Derivative of saturation specific humidity with respect to temperature [kg/kg/K].

e: Array

Vapor pressure [Pa].

qsatsurf: Array

Saturation specific humidity at surface temperature [kg/kg].

wCO2: Array

Kinematic CO2 flux [kg/kg m/s] or [mol m-2 s-1].

cliq: Array

Wet fraction of the canopy [-].

temp_soil_tend: Array

Soil temperature tendency [K s-1].

wgtend: Array

Soil moisture tendency [m3 m-3 s-1].

wltend: Array

Canopy water storage tendency [m s-1].

le_veg: Array

Latent heat flux from vegetation [W m-2].

le_liq: Array

Latent heat flux from liquid water [W m-2].

le_soil: Array

Latent heat flux from soil [W m-2].

le: Array

Total latent heat flux [W m-2].

hf: Array

Sensible heat flux [W m-2].

gf: Array

Ground heat flux [W m-2].

le_pot: Array

Potential latent heat flux [W m-2].

le_ref: Array

Reference latent heat flux [W m-2].

vpd: Array

Vapor pressure deficit [Pa].

class abcmodel.land.standard.AbstractStandardLandModel(a=0.219, b=4.9, p=4.0, cgsat=3.56e-06, wsat=0.472, wfc=0.323, wwilt=0.171, w2=0.21, d1=0.1, c1sat=0.132, c2ref=1.8, lai=2.0, gD=0.0, rsmin=110.0, rssoilmin=50.0, cveg=0.85, wmax=0.0002, lam=5.9)

Bases: AbstractLandModel

Abstract standard land surface model with comprehensive soil-vegetation dynamics.

Parameters:

• a (float) – Clapp and Hornberger (1978) retention curve parameter. Default is 0.219.

• b (float) – Clapp and Hornberger (1978) retention curve parameter. Default is 4.90.

• p (float) – Clapp and Hornberger (1978) retention curve parameter. Default is 4.0.

• cgsat (float) – saturated soil heat capacity [J m-3 K-1]. Default is 3.56e-6.

• wsat (float) – saturated soil moisture content [m3 m-3]. Default is 0.472.

• wfc (float) – soil moisture content at field capacity [m3 m-3]. Default is 0.323.

• wwilt (float) – soil moisture content at wilting point [m3 m-3]. Default is 0.171.

• w2 (float) – soil moisture content at the second layer [m3 m-3]. Default is 0.21.

• d1 (float) – depth of the top soil layer [m]. Default is 0.1.

• c1sat (float) – saturated soil hydraulic conductivity parameter [-]. Default is 0.132.

• c2ref (float) – reference soil hydraulic conductivity parameter [-]. Default is 1.8.

• lai (float) – leaf area index [m2 m-2]. Default is 2.0.

• gD (float) – canopy rad extinction coefficient [-]. Default is 0.0.

• rsmin (float) – minimum stomatal resistance [s m-1]. Default is 110.0.

• rssoilmin (float) – minimum soil resistance [s m-1]. Default is 50.0.

• cveg (float) – vegetation fraction [-]. Default is 0.85.

• wmax (float) – maximum water storage capacity of the canopy [m]. Default is 0.0002.

• lam (float) – thermal diffusivity of the soil [W m-1 K-1]. Default is 5.9.

init_state(alpha=0.25, wg=0.21, temp_soil=285.0, temp2=286.0, surf_temp=290.0, wl=0.0, wq=0.0001, wtheta=0.1, rs=1000000.0, rssoil=1000000.0)

Initialize the model state.

Parameters:

• alpha (float) – albedo [-]. Default is 0.25.

• wg (float) – Volumetric soil moisture [m3 m-3]. Default is 0.21.

• temp_soil (float) – Soil temperature [K]. Default is 285.0.

• temp2 (float) – Deep soil temperature [K]. Default is 286.0.

• surf_temp (float) – Surface temperature [K]. Default is 290.0.

• wl (float) – Canopy water content [m]. Default is 0.0000.

• wq (float) – Kinematic moisture flux [kg/kg m/s]. Default is 1e-4.

• wtheta (float) – Kinematic heat flux [K m/s]. Default is 0.1.

• rs (float) – Surface resistance [s m-1]. Default is 1.0e6.

• rssoil (float) – Soil resistance [s m-1]. Default is 1.0e6.

Returns:

The initial land state.

integrate(state, dt)

Integrate model forward in time.

Parameters:

• state (StandardLandState) – the state object carrying all variables.

• dt (float) – the time step.

Returns:

The updated state object.

run(state)

Run the full land surface model for one time step.

Parameters:

state (AbstractCoupledState) – CoupledState.

Returns:

The updated land state object.

compute_dqsatdT(esat, theta, surf_pressure)

Compute the derivative of saturation vapor pressure with respect to temperature dqsatdT.

Notes

Using compute_esat(), the derivative of the saturated vapor pressure \(e_\text{sat}\) with respect to temperature \(T\) is given by

\[\frac{\text{d}e_\text{sat}}{\text{d} T} = e_\text{sat}\frac{17.2694(T-237.16)}{(T-35.86)^2},\]

which combined with compute_qsat() can be used to get

\[\frac{\text{d}q_{\text{sat}}}{\text{d} T} \approx \epsilon \frac{\frac{\text{d}e_\text{sat}}{\text{d} T}}{p}.\]

compute_e(q, surf_pressure)

Compute the vapor pressure e.

Notes

This function uses the same formula used in compute_esat(), but now factoring the vapor pressure \(e\) as a function of specific humidity \(q\) and surface pressure \(p\), which give us

\[e = q \cdot p / 0.622.\]

abstractmethod update_surface_resistance(state)

Abstract method to update surface resistance.

abstractmethod update_co2_flux(state)

Abstract method to update CO2 flux.

compute_soil_resistance(wg)

Compute the soil resistance rssoil.

Notes

The soil resistance is calculated as

\[r_\text{soil} = r_\text{soil,min} \cdot f_2,\]

where the parameter \(r_\text{soil,min}\) is the minimum surface resistance and the correction function \(f_2\) is given by

\[\begin{split}f_2 = \begin{cases} \frac{w_\text{fc} - w_\text{wilt}}{w_g - w_\text{wilt}}, & \text{if } w_g > w_\text{wilt} \\ 10^8, & \text{otherwise}, \end{cases}\end{split}\]

where the model parameters \(w_\text{fc}\) and \(w_\text{wilt}\) are the field capacity and wilting point, respectively, and the variable \(w_g\) is the soil water content.

References

Equations 9.28 and 9.31 from the CLASS book.

compute_cliq(wl)

Compute the wet fraction cliq.

Notes

The wet fraction is defined as

\[c_{\text{liq}} = \frac{W_l}{\text{LAI}\cdot W_{\text{max}}},\]

where \(W_l\) is the water layer depth, \(\text{LAI}\) is the leaf area index and \(W_{\text{max}}\) is the thickness of the water layer on wet vegetation. In case \(W_l > \text{LAI}\cdot W_{\text{max}}\), the wet fraction is set to 1.

References

Equation 9.19 from the CLASS book.

compute_skin_temperature(net_rad, theta, q, qsat, dqsatdT, ra, rs, rssoil, cliq, temp_soil)

Compute the skin temperature surf_temp.

Notes

The skin temperature is obtained by solving the surface energy balance

\[R_n = H + LE_{\text{veg}} + LE_{\text{liq}} + LE_{\text{soil}} + G\]

where \(R_n\) is the net rad, \(H\) is the sensible heat flux (see compute_hf()), \(LE_{\text{veg}}\) is the latent heat flux from vegetation (see compute_le_veg()), \(LE_{\text{liq}}\) is the latent heat flux from dew on leaves (see compute_le_liq()), \(LE_{\text{soil}}\) is the latent heat flux from the soil (see compute_le_soil()) and \(G\) is the ground heat flux (see compute_gf()).

The equation is solved for the skin temperature \(T_s\) by factoring out \(T_s\) from the above, giving us

\[T_s = \frac{ R_n + \frac{\rho c_p}{r_a} \theta + c_{\text{veg}} (1-c_{\text{liq}}) \frac{\rho L_v}{r_a + r_s} (\frac{\text{d}q_{\text{sat}}}{\text{d}T} \theta - q_{\text{sat}} + q) + (1-c_{\text{veg}}) \frac{\rho L_v}{r_a + r_{s,\text{soil}}} (\frac{\text{d}q_{\text{sat}}}{\text{d}T} \theta - q_{\text{sat}} + q) + c_{\text{veg}} c_{\text{liq}} \frac{\rho L_v}{r_a} (\frac{\text{d}q_{\text{sat}}}{\text{d}T} \theta - q_{\text{sat}} + q) + \Lambda T_{\text{soil}} }{ \frac{\rho c_p}{r_a} + c_{\text{veg}} (1-c_{\text{liq}}) \frac{\rho L_v}{r_a + r_s} \frac{\text{d}q_{\text{sat}}}{\text{d}T} + (1-c_{\text{veg}}) \frac{\rho L_v}{r_a + r_{s,\text{soil}}} \frac{\text{d}q_{\text{sat}}}{\text{d}T} + c_{\text{veg}} c_{\text{liq}} \frac{\rho L_v}{r_a} \frac{\text{d}q_{\text{sat}}}{\text{d}T} + \Lambda }.\]

The terms computed in the equation above in each related function energy flux related method. This approach ensures that the computed skin temperature is consistent with the partitioning of energy fluxes as calculated by the other methods in this class.

compute_le_veg(surf_temp, theta, q, qsat, dqsatdT, ra, rs, cliq)

Compute the latent heat flux (transpiration) from vegetation le_veg.

Notes

The latent heat flux is given by

\[LE_{\text{veg}} = \frac{\rho L_v}{r_a+r_s}(q_{\text{sat}}(T_s)-⟨q⟩),\]

where \(\rho\) is the density of air, \(L_v\) is the latent heat of vaporization, \(r_a\) is the aerodynamic resistance, \(r_s\) is the soil resistance, \(q_{\text{sat}}(T_s)\) is the saturation specific humidity at surface temperature, \(⟨q⟩\) is the specific humidity at the surface.

\(q_{\text{sat}}(T_s)\) has very short time-scales because of the small heat capacity (excluding vegetation) of the surface layer and is hard to measure. Consequently, we get \(q_{\text{sat}}(T_s)\) implicitly using

\[q_{\text{sat}}(T_s) = \frac{\text{d}q_{\text{sat}}}{\text{d}T}(\theta_s-\theta),\]

where \(\theta_s\) and \(\theta\) are the potential temperature of the surface layer and mixed layer, respectively.

In the end, we scale the latent heat flux by the vegetation cover fraction \(c_{\text{veg}}\) and the liquid water content \(c_{\text{liq}}\) and return

\[c_{\text{veg}}(1-c_{\text{liq}})LE_{\text{veg}}.\]

References

Equation 9.15 from the CLASS book.

compute_le_liq(surf_temp, theta, q, qsat, dqsatdT, ra, cliq)

Compute the latent heat flux on the leaf (dew) le_liq.

Notes

We proceed just like in compute_le_veg(), but omitting vegetation’s resistance \(r_s\), with the assumption that water at the leaf is ready to be evaporated, giving us

\[LE_{\text{liq}} = \frac{\rho L_v}{r_a}(q_{\text{sat}}(T_s)-⟨q⟩).\]

In the end, we scale the result by the fraction of liquid water content \(c_{\text{liq}}\) and the fraction of vegetation \(c_{\text{veg}}\).

References

Equation 9.18 from the CLASS book.

compute_le_soil(surf_temp, theta, q, qsat, dqsatdT, ra, rssoil)

Compute the latent heat flux on the soil (evaporation) le_soil.

Notes

We proceed just like in compute_le_veg(), but instead of considering resistance from the vegetation, we consider the resistance from the soil \(r_{soil}\), giving us

\[LE_{\text{soil}} = \frac{\rho L_v}{r_a + r_{soil}}(q_{\text{sat}}(T_s)-⟨q⟩)\]

In the end, we scale the result by the fraction of soil \(c_{\text{soil}} = 1 - c_{\text{veg}}\).

References

Equation 9.21 from the CLASS book.

compute_wltend(le_liq)

Compute the water layer depth tendency tendency wltend.

Notes

The water layer depth tendency is the rate at which water is added to or taken from the vegetation, described by

\[\frac{\text{d} w}{\text{d} t} = -\frac{LE_{\text{liq}}}{\rho_w L_v},\]

where \(LE_{\text{liq}}\) is dew, \(\rho_w\) is water density and \(L_v\) is the latent heat of vaporization.

References

Equation 9.20 from the CLASS book, with sign convention.

compute_le(le_soil, le_veg, le_liq)

Compute the evapotranspiration (latent heat flux) le.

Notes

The sum of

• transpiration from vegetation in compute_le_veg();

• evaporation from bare soil in compute_le_soil();

• evaporation from wet leaves (dew) in compute_le_liq().

compute_hf(surf_temp, theta, ra)

Compute the sensible heat flux hf.

Notes

The sensible heat flux is given by

\[H = \frac{\rho c_p}{r_a} (T_s - \theta),\]

where \(\rho\) is the air density, \(c_p\) is the specific heat capacity of air, \(r_a\) is the aerodynamic resistance, \(T_s\) is the surface temperature and \(\theta\) is the mixed layer air potential temperature.

References

Equation 9.13 from the CLASS book, but why are we using \(T_s\) instead of \(\theta_s\)? Probably because the variations of pressure are not significant enough.

compute_gf(surf_temp, temp_soil)

Compute the ground heat flux gf.

Notes

The ground heat flux is given by

\[G = \Lambda (T_s - T_{soil}),\]

where \(\Lambda\) is the conductivity of the skin layer, \(T_s\) is the surface temperature and \(T_{soil}\) is the soil temperature.

References

Equation 9.33 from the CLASS book.

compute_le_pot(net_rad, gf, dqsatdT, qsat, q, ra)

Compute the potential latent heat flux le_pot.

Notes

The potential latent heat flux is given by

\[LE_{\text{pot}} = \frac{ \frac{\text{d}q_{sat}}{\text{d} T} (R_n - G) + \frac{\rho c_p}{r_a} (q_{\text{sat}} - q) }{ \frac{\text{d}q_{sat}}{\text{d} T} + \frac{\rho c_p}{L_v} },\]

which is the Penman-Monteith equation assuming no soil resistance.

References

Equation 9.16 from the CLASS book.

compute_le_ref(net_rad, gf, dqsatdT, qsat, q, ra)

Compute the reference latent heat flux le_ref.

Notes

The reference latent heat flux is given by

\[LE_{\text{ref}} = \frac{ \frac{\text{d}q_{sat}}{\text{d} T} (R_n - G) + \frac{\rho c_p}{r_a} (q_{\text{sat}} - q) }{ \frac{\text{d}q_{sat}}{\text{d} T} + \frac{\rho c_p}{L_v}( 1 + \frac{r_{s,\text{min}}}{\text{LAI} \cdot r_a} ) },\]

which is the Penman-Monteith equation assuming that the soil resistance is given by \(r_{s,\text{min}} / \text{LAI}\), i.e., no correction functions are applied.

References

Equation 9.16 from the CLASS book.

compute_temp_soil_tend(gf, temp_soil, temp2)

Compute the soil temperature tendency temp_soil_tend.

Notes

The dynamics of heat transport in the soil is given by

\[\frac{\text{d}T_s}{\text{d}t} = C_T G - \frac{2\pi}{\tau} (T_s - T_2),\]

\(T_2\) is the temperature of the second layer in the soil, \(T_s\) is the soil temperature, where \(\tau\) is the time constant of one day (86400s), \(G\) is the ground the heat flux and and \(C_T\) is the surface soil/vegetation heat capacity, which can be parametrized as

\[C_T = C_{T,\text{sat}} \left(\frac{w_{\text{sat}}}{w_2}\right)^{\frac{b}{2\log(10)}}\]

where \(C_{T,\text{sat}}\) is the saturated heat capacity, \(w_{\text{sat}}\) is the saturation water content, \(w_2\) is the water content at the second layer and \(b\) is a parameter from Clapp and Hornberger (1978). I have no idea where this log comes from.

References

Equation 9.32 of the CLASS book.

compute_wgtend(wg, le_soil)

Compute the soil moisture tendency wgtend.

Notes

The dynamics of soil moisture in the top soil layer is described by

(1)\[\frac{\mathrm{d}w_g}{\mathrm{d}t} = -\frac{C_1}{\rho_w d_1} \frac{LE_{\text{soil}}}{L_v} - \frac{C_2}{\tau} (w_g - w_{eq}),\]

where the coefficients \(C_1\) and \(C_2\) are calculated as

\[C_1 = C_{1,\text{sat}} \left(\frac{w_{sat}}{w_g}\right)^{b/2 + 1},\]

\[C_2 = C_{2,\text{ref}} \left(\frac{w_2}{w_{sat} - w_2}\right),\]

where \(C_{1,\text{sat}}\) and \(C_{2,\text{sat}}\) are parameters from Clapp-Hornberger (1978) and the equilibrium soil moisture is given by

\[w_{eq} = w_2 - w_{sat} a \left(\left(\frac{w_2}{w_{sat}}\right)^p \left[1 - \left(\frac{w_2}{w_{sat}}\right)^{8p}\right]\right).\]

In these equations, \(w_g\) is the volumetric soil moisture in the top layer, \(LE_{\text{soil}}\) is the latent heat flux from the soil, \(L_v\) is the latent heat of vaporization, \(\rho_w\) is the density of water, \(d_1\) is the depth of the first soil layer, \(\tau\) is a time constant (here, 86400 s = 1 day), \(w_2\) is the soil moisture in the second layer, \(w_{sat}\) is the saturated soil moisture, and \(a\), \(b\) and \(p\) are parameters from Clapp-Hornberger (1978).

In (1), the first term represents the loss of soil moisture due to evaporation, and the second term represents the relaxation of soil moisture toward equilibrium with the lower layer.

References

• (9.34)–(9.37) in the CLASS book.

• Clapp, R. B., & Hornberger, G. M. (1978). Empirical equations for some soil hydraulic properties. Water resources research, 14(4), 601-604.

compute_wtheta(hf)

Compute the kinematic heat flux wtheta.

Notes

The kinematic heat flux \(\overline{(w'\theta')}_s\) is directly related to the sensible heat flux \(H\) through

\[\overline{(w'\theta')}_s = \frac{H}{\rho c_p},\]

where \(\rho\) is the density of air and \(c_p\) is the specific heat capacity of air at constant pressure.

compute_wq(le)

Compute the kinematic moisture flux wq.

Notes

The kinematic moisture flux \(\overline{(w'q')}_s\) is directly related to the latent heat flux \(LE\) through

\[\overline{(w'q')}_s = \frac{LE}{\rho L_v},\]

where \(\rho\) is the density of air and \(L_v\) is the latent heat of vaporization.

compute_vpd(q, qsat)

Compute the vapor pressure deficit vpd.

Notes

The vapor pressure deficit \(\d_q\) is defined as the difference between the saturation vapor pressure \(\q_{sat}\) and the actual vapor pressure \(e\).