Biosphere

Biosphere#

Submodules#

There are two possible implementations of biosphere models:

Module contents#

class abcmodel.land.biosphere.JarvisStewartModel(rsmin=110.0, lai=2.0, gD=0.0, cveg=0.85, wmax=0.0002, wwilt=0.171, wfc=0.323, w2=0.21)[source]#

Bases: AbstractBiosphereModel[JarvisStewartState]

Jarvis-Stewart biosphere model with empirical surface resistance.

Parameters:

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

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

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

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

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

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

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

init_state(rs=1000000.0, wl=0.0, cliq=0.0, wCO2=0.0)[source]#

Initialize the biosphere state.

Parameters:

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

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

  • cliq (float) – Wet fraction of canopy [-]. Default is 0.0.

  • wCO2 (float) – Kinematic CO2 flux [mol m-2 s-1]. Default is 0.0.

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

Returns:

The initialized JarvisStewartState.

run(state)[source]#

Compute biosphere surface resistance and canopy wet fraction.

compute_f1(in_srad)[source]#

Compute the radiation stress factor f1.

Notes

The radiation factor follows the Jarvis (1976) formulation:

\[f_1 = \frac{1}{\min\!\left(1,\, \dfrac{0.004\,R_s + 0.05}{0.81\,(0.004\,R_s + 1)}\right)}\]

where \(R_s\) is the incoming solar radiation.

compute_f2(wg)[source]#

Compute the soil moisture stress factor f2.

Notes

The soil moisture factor follows the Jarvis (1976) formulation:

\[f_2 = \max\!\left(1,\, \frac{w_{\text{fc}} - w_{\text{wilt}}} {w_g - w_{\text{wilt}}}\right)\]

where \(w_g\) is the surface soil moisture, \(w_{\text{fc}}\) is the field capacity and \(w_{\text{wilt}}\) is the wilting point. When the second-layer soil moisture \(w_2\) drops below the wilting point, the factor is set to a large value (effectively closing the stomata).

compute_f3(esat, e)[source]#

Compute the vapour pressure deficit stress factor f3.

Notes

The VPD factor follows the Jarvis (1976) formulation:

\[f_3 = \exp\!\left(\frac{g_D \, D}{100}\right)\]

where \(D = e_{\text{sat}} - e\) is the vapour pressure deficit, \(e_{\text{sat}}\) is the saturation vapour pressure, \(e\) is the actual vapour pressure, and \(g_D\) is the canopy radiation extinction coefficient.

compute_f4(theta)[source]#

Compute the temperature stress factor f4.

Notes

The temperature factor follows the Jarvis (1976) formulation:

\[f_4 = \frac{1}{1 - 0.0016\,(298 - \theta)^2}\]

where \(\theta\) is the potential temperature [K].

compute_cliq(wl)[source]#

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_wltend(le_liq)[source]#

Compute the water layer depth 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.

run_tends(state, surf_state)[source]#

Compute biosphere tendencies that depend on surface fluxes.

integrate(state, dt)[source]#

Integrate canopy water content forward in time.

class abcmodel.land.biosphere.JarvisStewartState(rs, wl, cliq, wCO2, cveg, wltend=<factory>)[source]#

Bases: AbstractBiosphereState

Jarvis-Stewart biosphere state.

rs: Array#

Surface resistance [s m-1].

wl: Array#

Canopy water content [m].

cliq: Array#

Wet fraction of canopy [-].

wCO2: Array#

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

cveg: Array#

Vegetation fraction [-].

wltend: Array#

Canopy water content tendency [m].

class abcmodel.land.biosphere.AgsModel(c3c4='c3', lai=2.0, cveg=0.85, wmax=0.0002, wwilt=0.171, wfc=0.323, w2=0.21)[source]#

Bases: AbstractBiosphereModel[AgsState]

Ags land surface biosphere model with coupled photosynthesis and stomatal conductance.

Parameters:

  • c3c4 (str) – string indicating whether the model should use C3 or C4 photosynthesis. Default is “c3”.

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

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

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

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

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

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

init_state(rs=1000000.0, wl=0.0, cliq=0.0, wCO2=0.0)[source]#

Initialize the Ags state.

Parameters:

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

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

  • cliq (float) – Wet fraction of canopy [-]. Default is 0.0.

  • wCO2 (float) – Total CO2 flux [mol m-2 s-1]. Default is 0.0.

Returns:

The initialized AgsState.

run(state)[source]#

Compute stomatal resistance and CO2 fluxes.

compute_co2comp(thetasurf)[source]#

Compute the CO₂ compensation concentration co2comp.

Notes

The CO₂ compensation point \(\Gamma\) is the CO₂ concentration at which net photosynthesis is zero. It follows a Q₁₀ temperature response:

\[\Gamma = \Gamma_{298} \cdot \rho \cdot Q_{10}^{\,0.1\,(\theta_s - 298)}\]

where \(\Gamma_{298}\) is the compensation point at 298 K, \(\rho\) is the air density, \(Q_{10}\) is the relative increase per 10 K, and \(\theta_s\) is the surface potential temperature.

compute_gm(thetasurf)[source]#

Compute the mesophyll conductance gm.

Notes

Mesophyll conductance \(g_m\) controls the diffusion of CO₂ from intercellular spaces to the sites of carboxylation. It follows a temperature response with a Q₁₀ factor and high/ low temperature inhibition:

\[g_m = \frac{g_{m,298} \cdot Q_{10}^{\,0.1\,(\theta_s - 298)}} {\bigl(1 + e^{0.3\,(T_1 - \theta_s)}\bigr) \bigl(1 + e^{0.3\,(\theta_s - T_2)}\bigr)}\]

where \(g_{m,298}\) is the mesophyll conductance at 298 K, \(\theta_s\) is the surface potential temperature, and \(T_1, T_2\) are temperature thresholds.

compute_fmin(gm)[source]#

Compute the minimum stomatal conductance factor fmin.

Notes

The minimum conductance factor \(f_{\min}\) is derived from the quadratic relation between minimum stomatal conductance \(g_{\min}\) and mesophyll conductance \(g_m\):

\[f_{\min} = \frac{-f_0 + \sqrt{f_0^2 + \dfrac{4 g_{\min} g_m}{\nu}}}{2 g_m}, \qquad f_0 = \frac{g_{\min}}{\nu} - \frac{g_m}{9},\]

where \(\nu = 1.6\) is the ratio of diffusivity of water vapour to CO₂, and \(g_{\min}\) is the minimum stomatal conductance.

compute_ds(surf_temp, e)[source]#

Compute the vapour pressure deficit ds.

Notes

The vapour pressure deficit at the surface is given by

\[D_s = \frac{e_{\text{sat}}(T_s) - e}{1000},\]

where \(e_{\text{sat}}\) is the saturation vapour pressure at the surface temperature \(T_s\) and \(e\) is the actual vapour pressure. The result is in kPa.

compute_d0(fmin)[source]#

Compute the reference vapour pressure deficit d0.

Notes

The reference VPD is derived from the minimum conductance factor:

\[D_0 = \frac{f_0 - f_{\min}}{a_d},\]

where \(f_0\) is a shape parameter and \(a_d\) is the sensitivity of the VPD response.

compute_internal_co2(ds, d0, fmin, co2, co2comp)[source]#

Compute the intercellular CO₂ concentration ci.

Notes

The intercellular CO₂ concentration \(C_i\) is computed from the CO₂ absorption concentration and the compensation point:

\[\begin{split}c_f &= f_0 \left(1 - \frac{D_s}{D_0}\right) + f_{\min} \frac{D_s}{D_0} \\ \text{CO}_{2,\text{abs}} &= \text{CO}_2 \frac{M_{\text{CO}_2}} {M_{\text{air}}} \rho \\ C_i &= c_f (\text{CO}_{2,\text{abs}} - \Gamma) + \Gamma\end{split}\]

where \(c_f\) is the fractional reduction factor, \(\text{CO}_2\) is the atmospheric CO₂ concentration, \(M_{\text{CO}_2}\) and \(M_{\text{air}}\) are the molar masses of CO₂ and dry air, and \(\rho\) is the air density.

Returns:

A tuple (ci, co2abs).

compute_max_gross_primary_production(thetasurf)[source]#

Compute the maximal gross primary production ammax.

Notes

The maximum gross primary production \(A_{m,\max}\) follows a temperature response identical in structure to mesophyll conductance:

\[A_{m,\max} = \frac{A_{m,298} \cdot Q_{10}^{\,0.1\,(\theta_s - 298)}} {\bigl(1 + e^{0.3\,(T_1 - \theta_s)}\bigr) \bigl(1 + e^{0.3\,(\theta_s - T_2)}\bigr)}\]

where \(A_{m,298}\) is the value at 298 K and \(\theta_s\) is the surface potential temperature.

compute_soil_moisture_stress_factor(w2)[source]#

Compute the soil moisture stress factor fstr.

Notes

The soil moisture stress factor \(\beta_w\) is computed from the relative soil moisture:

\[\beta_w = \frac{w_2 - w_{\text{wilt}}} {w_{\text{fc}} - w_{\text{wilt}}}\]

clipped to \([\varepsilon, 1]\). The stress factor is then adjusted using a piecewise function depending on the parameter \(c_{\beta}\):

\[\begin{split}f_{\text{str}} = \begin{cases} \beta_w & c_\beta = 0 \\[4pt] \dfrac{1 - e^{-p \beta_w}}{1 - e^{-p}} & c_\beta > 0 \end{cases}\end{split}\]

where the shape parameter \(p\) increases with \(c_{\beta}\).

compute_gross_assimilation(ammax, gm, ci, co2comp)[source]#

Compute the gross assimilation rate am.

Notes

The gross assimilation rate follows an exponential approach to saturation (Collatz et al., 1991):

\[A_m = A_{m,\max} \left(1 - \exp\!\left( -\frac{g_m\,(C_i - \Gamma)}{A_{m,\max}} \right)\right)\]

where \(A_{m,\max}\) is the maximal gross primary production, \(g_m\) is the mesophyll conductance, \(C_i\) is the intercellular CO₂ concentration, and \(\Gamma\) is the CO₂ compensation concentration.

compute_dark_respiration(am)[source]#

Compute the dark respiration rate rdark.

Notes

Dark respiration is proportional to the gross assimilation rate:

\[R_{\text{dark}} = \frac{A_m}{9}\]

where \(A_m\) is the gross assimilation rate.

compute_absorbed_par(in_srad)[source]#

Compute the absorbed photosynthetically active radiation par.

Notes

The absorbed PAR is estimated as 50% of the incoming solar radiation, scaled by the vegetation fraction, with a lower bound:

\[\text{PAR} = \max\!\left(0.5 \cdot R_s \cdot c_{\text{veg}},\, 0.1\right)\]

where \(R_s\) is the incoming solar radiation and \(c_{\text{veg}}\) is the vegetation fraction.

compute_canopy_co2_conductance(alphac, par, am, rdark, fstr, co2abs, co2comp, ds, d0, fmin)[source]#

Compute the canopy CO₂ conductance gcco2.

Notes

The canopy CO₂ conductance \(g_{c,\text{CO}_2}\) is computed by scaling leaf-level photosynthesis to the canopy using the big-leaf approach with the exponential integral \(E_1\) (Sellers et al., 1996):

\[\begin{split}y &= \frac{\alpha_c k_x \text{PAR}}{A_m + R_{\text{dark}}} \\ A_n &= (A_m + R_{\text{dark}}) \left(1 - \frac{E_1(y e^{-k_x L}) - E_1(y)}{k_x L} \right) \\ D_* &= \frac{D_0}{a_1 (f_0 - f_{\min})} \\ g_{c,\text{CO}_2} &= L \left(\frac{g_{\min}}{\nu} + \frac{a_1 f_{\text{str}} A_n} {(\text{CO}_{2,\text{abs}} - \Gamma) (1 + D_s / D_*)}\right)\end{split}\]

where \(L\) is the leaf area index, \(k_x\) is the extinction coefficient, \(\nu = 1.6\) is the diffusivity ratio, and \(a_1 = 1 / (1 - f_0)\).

compute_rs(gcco2)[source]#

Compute the surface resistance rs.

Notes

The surface (stomatal) resistance is related to the canopy CO₂ conductance by

\[r_s = \frac{1}{1.6 \, g_{c,\text{CO}_2}}\]

where the factor \(1.6\) is the ratio of diffusivity of water vapour to CO₂, and \(g_{c,\text{CO}_2}\) is the canopy CO₂ conductance.

compute_light_use_efficiency(co2abs, co2comp)[source]#

Compute the light use efficiency alphac.

Notes

The light use efficiency depends on the CO₂ concentration:

\[\alpha_c = \alpha_0 \, \frac{\text{CO}_{2,\text{abs}} - \Gamma} {\text{CO}_{2,\text{abs}} + 2\Gamma}\]

where \(\alpha_0\) is the quantum efficiency and \(\Gamma\) is the CO₂ compensation concentration.

compute_surface_co2_resistance(gcco2)[source]#

Compute the surface resistance to CO₂ rsCO2.

Notes

The surface resistance to CO₂ is the reciprocal of the canopy CO₂ conductance:

\[r_{s,\text{CO}_2} = \frac{1}{g_{c,\text{CO}_2}}\]

where \(g_{c,\text{CO}_2}\) is the canopy CO₂ conductance.

compute_net_assimilation(co2abs, ci, ra, rsCO2)[source]#

Compute the net CO₂ assimilation rate an.

Notes

The net assimilation rate follows Fick’s law of diffusion:

\[A_n = -\frac{\text{CO}_{2,\text{abs}} - C_i} {r_a + r_{s,\text{CO}_2}}\]

where \(\text{CO}_{2,\text{abs}}\) is the CO₂ absorption concentration, \(C_i\) is the intercellular CO₂ concentration, \(r_a\) is the aerodynamic resistance, and \(r_{s,\text{CO}_2}\) is the surface resistance to CO₂.

compute_soil_water_fraction(wg)[source]#

Compute the soil water fraction fw.

Notes

The soil water fraction used for respiration scaling is

\[f_w = \frac{c_w \, w_{\max}}{w_g + w_{\min}}\]

where \(w_g\) is the surface soil moisture, \(w_{\max}\) and \(w_{\min}\) are empirical parameters, and \(c_w\) is a scaling constant.

compute_respiration(temp_soil, fw)[source]#

Compute the soil respiration rate resp.

Notes

Soil respiration follows an Arrhenius-type temperature response with a moisture limitation:

\[R = R_{10} \cdot (1 - f_w) \cdot \exp\!\left(\frac{E_0}{283.15 \cdot R} \left(1 - \frac{283.15}{T_{\text{soil}}} \right)\right)\]

where \(R_{10}\) is the respiration rate at 283.15 K, \(f_w\) is the soil water fraction, \(E_0\) is the activation energy, and \(T_{\text{soil}}\) is the soil temperature.

scale_flux_to_mol(flux)[source]#

Scale a flux to mol m⁻² s⁻¹.

compute_cliq(wl)[source]#

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_wltend(le_liq)[source]#

Compute the water layer depth 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.

run_tends(state, surf_state)[source]#

Compute biosphere tendencies that depend on surface fluxes.

integrate(state, dt)[source]#

Integrate canopy water content forward in time.

class abcmodel.land.biosphere.AgsState(rs, wl, cliq, wCO2, cveg, rsCO2=<factory>, gcco2=<factory>, ci=<factory>, co2abs=<factory>, wCO2A=<factory>, wCO2R=<factory>, wltend=<factory>)[source]#

Bases: AbstractBiosphereState

A-gs biosphere state.

rs: Array#

Surface resistance [s m-1].

wl: Array#

Canopy water content [m].

cliq: Array#

Wet fraction of canopy [-].

wCO2: Array#

Total CO2 flux [mol m-2 s-1].

cveg: Array#

Vegetation fraction [-].

rsCO2: Array#

Stomatal resistance to CO2.

gcco2: Array#

Conductance to CO2.

ci: Array#

Intercellular CO2 concentration.

co2abs: Array#

CO2 assimilation rate / concentration.

wCO2A: Array#

Net assimilation flux [mol m-2 s-1].

wCO2R: Array#

Respiration flux [mol m-2 s-1].

wltend: Array#

Canopy water content tendency [m].