Soil water & root uptake
theory
This page builds on Assimilation & hydraulics and the TF24 model. Read those first. They introduce the leaf-level profit-maximisation model that this page connects to soil water.
Only the hydraulically explicit strategies — TF24 and TF24f — carry a soil water balance. FF16 and K93 have no below-ground state: FF16’s environment tracks canopy openness, while K93’s tracks the cumulative basal area of larger neighbours. Throughout this page, “the environment” means TF24_Environment, not the shared base class.
The idea first
A plant’s leaves are only half the story. We also need to track how water moves through the soil. The assimilation & hydraulics page starts with a soil water potential \(\psi_s\) and shows how that potential affects carbon gain and water loss. This page explains where \(\psi_s\) comes from.
Imagine the soil beneath a patch as a stack of buckets. Rain enters the top bucket. As that bucket approaches saturation, more water drains into the layer below. The same process continues down the column, with water leaving the bottom as deep drainage.
Plants draw water from the layers reached by their roots. Uptake depends on how wet each layer is and on how much resistance the roots present, including the work required to lift water to the root collar. Wetter soil requires less suction to extract water. Together, soil moisture and root resistance determine the water potential at the root collar. That combined potential — rather than a simple average across layers — is what feeds the leaf model described elsewhere.
The rest of this page makes this precise.
The TF24 implementation uses two related conventions. The soil-retention and leaf calculations use the positive magnitude of water potential, so a larger value means a more negative physical potential. The soil-to-root transport calculation uses signed, negative potentials so it can evaluate the physical gradient directly.
To keep the distinction visible, this page writes the positive magnitude as \(\psi^\ast\) and the signed value as \(\Psi=-\psi^\ast\). The root-collar potential \(P_{x,r}\) in Equation 5 is also signed and normally negative.
The soil column: \(N\) layers, one bucket each
The soil beneath a patch is divided into \(N\) layers (soil_number_of_depths, default \(N = 5\)), from the surface to a total depth of depth (default 1.5 m). Layer \(i\) has thickness \(\Delta z_i\) (dz; all layers have the same thickness by default: depth \(/ N\)), a lower-boundary depth \(z_i\), and a midpoint depth \(\bar z_i\) (z_mid). The root-uptake model in Section 6 treats this midpoint as the depth from which the layer’s water is drawn.
Each layer carries one state variable, its volumetric soil moisture \(\theta_i\) (m\(^3\) water m\(^{-3}\) soil). The saturated moisture content \(\theta_{\rm sat}\) (soil_moist_sat, default 0.428) is a reference value in the retention and conductivity curves, not a hard upper bound on this stored state. The mass balance for layer \(i\) is
\[ \frac{{\rm d}\theta_i}{{\rm d}t} = \frac{q_{{\rm in},i} - q_{{\rm out},i} - u_i}{\Delta z_i}, \tag{1}\]
where \(q_{{\rm in},i}\) is the inflow from above, \(q_{{\rm out},i}\) is gravitational drainage from the layer’s base, and \(u_i\) is the total root water uptake by plants rooted in layer \(i\) (the resource_depletion vector passed in from the patch). Section 3 and Section 4 define \(q_{{\rm in}}\) and \(q_{{\rm out}}\); Section 6 defines \(u\).
Infiltration and runoff
Water enters the top layer (\(i = 0\)) as rainfall, but some of it runs off. The runoff share increases as the top layer approaches saturation. Infiltration follows a saturation-excess form,
\[ q_{{\rm in},0} = P\left[1 - a_{\rm infil}\left(\frac{\theta_0}{\theta_{\rm sat}}\right)^{b_{\rm infil}}\right]^{+}, \tag{2}\]
where \(P\) is the rainfall rate (the extrinsic driver rainfall, evaluated at the current time). The notation \([\,\cdot\,]^+\) means that the term is floored at zero, so infiltration cannot be negative. The parameter \(a_{\rm infil}\) controls the overall runoff response: 0 means no runoff, while 1 applies the full saturation-excess term. The parameter \(b_{\rm infil}\) controls how sharply runoff increases near saturation. For every layer below the surface, \(q_{{\rm in},i}\) is the drainage flux from the layer above, \(q_{{\rm out},i-1}\). Water therefore moves down the column one layer at a time.
Gravitational drainage
Water leaves the base of each layer at a rate set by its unsaturated hydraulic conductivity. Conductivity rises steeply with moisture content, following the Clapp & Hornberger (1978) form as parameterised by Zeng & Decker (2009, their Eq. 5):
\[ q_{{\rm out},i} = K(\theta_i) = K_{\rm sat}\left(\frac{\theta_i}{\theta_{\rm sat}}\right)^{2n_\psi + 3}, \tag{3}\]
where \(K_{\rm sat}\) (K_sat) is the saturated hydraulic conductivity and \(n_\psi\) (n_psi) is the retention-curve shape parameter also used in Equation 4. The same function, soil_K_from_soil_theta, is used for every layer. For this conductivity calculation, the input moisture is clamped to \([0, \theta_{\rm sat}]\): a non-positive value gives zero conductivity, and a value above saturation gives \(K_{\rm sat}\). Each layer’s outflow becomes the next layer’s inflow, while the outflow from the deepest layer leaves the column as deep drainage.
This is a first-order, one-way bucket scheme: drainage moves down the column, never up. The soil water balance does not include capillary rise or lateral flow between layers. The only water movement “against gravity” occurs inside the plant, along the root-to-collar hydraulic path described in Section 6.
From moisture to potential: the retention curve
Plants respond not to volumetric moisture directly, but to the corresponding water potential \(\psi\). The soil water retention curve converts between the two,
\[ \psi^\ast_{\rm soil}(\theta) = \frac{a_\psi}{10^6}\left(\frac{\theta}{\theta_{\rm sat}}\right)^{-n_\psi}, \tag{4}\]
(psi_from_soil_moist). The factor \(10^6\) converts \(a_\psi\) from Pa to MPa, the unit used throughout the leaf model. The parameters \(a_\psi\) (a_psi) and \(n_\psi\) (n_psi) define the same retention-curve family as Equation 3. As a layer dries (\(\theta \to 0\)), \(\psi^\ast_{\rm soil} \to \infty\): drier soil requires a root to pull harder to extract water. The inverse, soil_moist_from_psi, solves the same relationship for \(\theta\) given \(\psi\).
psi_from_soil_moist() returns the potential magnitude in MPa, as in Equation 4. Its apparent inverse, soil_moist_from_psi(), currently expects its potential argument in Pa, because it divides the input directly by a_psi before applying the inverse power. Thus, for a round trip, multiply the MPa result by \(10^6\) before passing it to soil_moist_from_psi().
This is an API asymmetry, not a physical distinction. The theory and the leaf model use MPa, so a future plant change to make the inverse accept MPa would be easier to use; until then, callers need to make the conversion explicitly.
\(\psi^\ast_{\rm soil}(\theta)\) diverges as \(\theta \to 0\), and the drainage rate Equation 3 is undefined for \(\theta < 0\). An explicit fixed-step solver can produce either problem briefly at the edge of a drought. plant prevents this with a residual-moisture floor, soil_moist_residual (default \(10^{-2}\) m\(^3\) m\(^{-3}\)). A layer at or below this floor cannot be dried further by Equation 1; only rewetting is allowed. The model also evaluates \(\psi^\ast_{\rm soil}\) at \(\max(\theta, \theta_r)\) rather than at \(\theta\), keeping the retention curve finite for a depleted layer. The floor is well below realistic operating moisture, so it does not affect non-drought runs. In addition, the resulting potential is capped at \(10^3\) MPa: at the residual floor, root conductance is already effectively zero, while the cap keeps the coupled hydraulic calculation finite. See issue #485 for the numerical failure mode the floor prevents.
Coupling to the plant: root-collar water potential
Each layer’s moisture state is first converted to a positive potential magnitude, \(\psi^\ast_{{\rm soil},i}\), via Equation 4. Before calculating soil-to-root flow, the implementation changes it to the signed potential \(\Psi_{{\rm soil},i}=-\psi^\ast_{{\rm soil},i}\). A plant with roots in several layers does not experience \(N\) separate root-collar potentials. The flows from all layers meet at one potential, \(P_{x,r}\), at the root collar.
Imagine each layer connected to the root collar by its own pipe. The pipe for layer \(i\) has two parts:
- a horizontal segment that resists movement from the soil into the root, \(r_{{\rm R},H,i}\);
- a vertical segment that resists movement up the root axis to the collar, \(r_{{\rm R},V,i}\).
The vertical resistance accumulates with depth because water from a deep layer must pass through every shallower root segment on its way up. Both resistances depend on the root carbon invested horizontally and vertically in that layer. The horizontal resistance is also increased by a root vulnerability curve. This curve has the same exponential form as the stem vulnerability curve on the assimilation & hydraulics page, but uses separate root parameters (root_c, root_b, root_psi_crit). As roots lose conductance under water stress, they become proportionately harder for water to pass through.
For a candidate signed root-collar potential \(P_{x,r}\) and signed layer potential \(\Psi_{{\rm soil},i}\), the water drawn from layer \(i\) (per unit plant leaf area) is
\[ E_i = \frac{\left(\Psi_{{\rm soil},i} - P_{x,r} - g\,\bar z_i\right)}{r_{{\rm R},i}}, \tag{5}\]
where \(r_{{\rm R},i} = r_{{\rm R},H,i} + r_{{\rm R},V,i}\) is the layer’s total resistance. The term \(g\,\bar z_i\) is the gravitational head that must be overcome to lift water from the layer midpoint \(\bar z_i\) to the collar, with \(g\) = gravity_head = \(9.8\times10^{-3}\) MPa m\(^{-1}\). Two special cases are handled exactly rather than with this general form: when \(P_{x,r} = \Psi_{{\rm soil},i}\), the layer is driven only by gravity; when the potential gradient exactly balances the gravitational head, \(E_i = 0\).
The root vulnerability curve is non-linear in \(\psi\). For that reason, the horizontal resistance in Equation 5 is averaged over the potential interval between the soil and the collar rather than evaluated at a single point. Specifically, \(r_{{\rm R},H,i}\) scales with the interval’s span divided by the integral of the vulnerability curve across it.
Summing \(E_i\) across layers gives the total water the root system can supply at a given \(P_{x,r}\). The model then solves for the root-collar potential and the leaf xylem potential \(\psi_l\) together, using the profit-maximisation procedure described in assimilation & hydraulics.
The solution must reconcile soil-side supply with the demand implied by the optimal stomatal conductance. Water arriving at the collar from the soil must equal the water carried onward through the root-to-leaf hydraulic path. In this way, the layer potentials from this page, together with gravity and root vulnerability, provide the “downstream water potential” required by the leaf model’s cost function. Solving for \(P_{x,r}\) links the soil water balance to leaf-level profit maximisation.
Diagnostics: cumulative fluxes
Alongside the \(N\) moisture states, the environment tracks four cumulative auxiliary states (aux_num = 4). These states integrate the water balance over time rather than reporting only instantaneous rates:
- cumulative rainfall \(\int P\,{\rm d}t\);
- cumulative infiltration \(\int q_{{\rm in},0}\,{\rm d}t\);
- cumulative deep drainage, the outflow lost from the bottom of the column, \(\int q_{{\rm out},N-1}\,{\rm d}t\);
- cumulative total root uptake, \(\int \sum_i u_i\,{\rm d}t\).
These running totals are analogous to the cumulative growth and seed output tracked for individual plants on the size-structured PDE page. They provide a convenient audit of a run’s water budget — rainfall in, runoff and drainage out, and uptake removed — without having to reconstruct it from instantaneous rates.
Current limitation: only light can be pinned
set_fixed_environment() lets a user fix the light environment at a chosen value, which is useful for isolating a plant’s response to light. There is no equivalent for soil water. The water balance in Equation 1 always runs dynamically, driven by rainfall and uptake; users cannot hold \(\psi^\ast_{\rm soil}\) constant at a chosen value. This is a known gap (TODO(#476)) in the shared Environment machinery, not a deliberate modelling choice. See ff16_environment.h, where the same TODO is recorded.
Where this leads
The per-layer potentials, root-collar solve, and cumulative fluxes on this page describe the supply side of the water economy. Assimilation & hydraulics describes the demand side: how the plant decides how much water to draw by optimising leaf xylem potential against the carbon gained. Together, the two pages describe TF24’s water economy. See the TF24 model page for how it fits into the rest of the strategy.