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 models — TF24 and its subclasses TF24f, TF24t and TF24w — 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.
Under TF24w, each plant also has a private root-zone column, over the ground its crown covers. The column follows the same infiltration, drainage and residual floor as the patch’s, loses only its own plant’s uptake, and mixes towards the patch’s mean moisture; the bare ground keeps the patch’s column.
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.
TF24 writes every water potential as a positive magnitude, so a larger value means a more negative physical potential; the signs live in the equations, not in the variables. This page writes the soil’s potential as \(\psi^\ast\). The uptake equation, Equation 5, is phylloptim’s and uses its symbols: \(\psi_{s,i}\) for the potential of soil layer \(i\), which is \(\psi^\ast_{{\rm soil},i}\), and \(\psi_c\) for the root-collar potential, both magnitudes.
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}, \qquad q_{{\rm in},i} = q_{{\rm out},i-1}\ (i > 0) \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 and floored at zero, \(P = \max(0, P_{\rm driver}(t))\). The floor is there because a spline through intermittent rain can undershoot below zero; flooring it adds the area of the undershoot to the rain received. 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.
Water can also arrive as a pulse: a scheduled event adds a depth \(d\) to one layer between solver steps, into layer 0 for rain, or deeper for irrigation or a rising water table. A pulse does not pass through Equation 2. The layer takes what it can still hold, \(\min(d, \Delta z_i [\theta_{\rm sat} - \theta_i]^{+})\), and the rest is pulse runoff. Under TF24w a pulse lands on every private column and on the bare ground, each capped in the same way.
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{\tilde\theta_i}{\theta_{\rm sat}}\right)^{2n_\psi + 3}, \qquad \tilde\theta_i = \min\left(\max(\theta_i, 0),\ \theta_{\rm sat}\right) \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, conductivity, is used for every layer, with that layer’s \(K_{\rm sat}\), \(\theta_{\rm sat}\) and \(n_\psi\). Its input moisture is clamped to \([0, \theta_{\rm sat}]\), giving \(\tilde\theta_i\): 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) = \min\left(a_\psi\left(\frac{\max(\theta, \theta_r)}{\theta_{\rm sat}}\right)^{-n_\psi},\ \psi^\ast_{\max}\right) \tag{4}\]
(psi_from_soil_moist). \(a_\psi\) (a_psi) is held in MPa, the unit used throughout the leaf model, so the curve needs no conversion. The parameters \(a_\psi\) and \(n_\psi\) (n_psi) define the same retention-curve family as Equation 3. As a layer dries, \(\psi^\ast_{\rm soil}\) rises steeply: drier soil requires a root to pull harder to extract water. The moisture is floored at the residual moisture \(\theta_r\) and the potential capped at \(\psi^\ast_{\max}\), as the callout below explains. The inverse, soil_moist_from_psi, solves the same relationship for \(\theta\) given \(\psi^\ast\), also in MPa, so the two round-trip. It applies neither the floor nor the cap, so it inverts Equation 4 only between them.
Without a floor, \(\psi^\ast_{\rm soil}(\theta)\) would diverge as \(\theta \to 0\), and the drainage rate Equation 3 would be 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 \(\psi^\ast_{\max}\) (soil_psi_max_): at the residual floor, root conductance is already effectively zero, while the cap keeps the coupled hydraulic calculation finite. While a layer sits on the floor, its drainage still passes to the layer below and its uptake is still booked in the uptake total, so the column’s water budget closes exactly only while no layer is on the floor. 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 potential magnitude, \(\psi_{s,i} = \psi^\ast_{{\rm soil},i}\), via Equation 4. A plant with roots in several layers does not experience \(N\) separate root-collar potentials. The flows from all layers meet at one potential, \(\psi_c\), 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, with resistance \(r_{H,\min,i}\) while the roots are fully conductive;
- a vertical segment that resists movement up the root axis to the collar, \(r_{V,\Sigma,i}\).
The vertical resistance accumulates with depth because water from a deep layer must pass through every shallower root segment on its way up: \(r_{V,\Sigma,i}\) is the sum of the vertical resistances of layers \(0\) to \(i\). 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 Weibull form as the stem vulnerability curve on the assimilation & hydraulics page, but uses separate root parameters (root_c, root_P50). As roots lose conductance under water stress, they become proportionately harder for water to pass through.
For a candidate root-collar potential \(\psi_c\), the water drawn from layer \(i\) (mol m\(^{-2}\) s\(^{-1}\) per unit plant leaf area) is
\[ E_i = \frac{\psi_c - \psi_{s,i} - \rho_w g z_i}{r_{H,\min,i}\,\Delta\psi_i / I_i + r_{V,\Sigma,i}}, \qquad E_\mathrm{up} = M_w \sum_{i \le L} E_i \\ \Delta\psi_i = |\psi_c - \psi_{s,i}|,\quad I_i = \hat F_r(\psi_\mathrm{hi}) - \hat F_r(\max(\psi_\mathrm{lo}, 0)) + \max(0, -\psi_\mathrm{lo}) \\ E_i = \frac{-\rho_w g z_i}{r_{H,\min,i}/\hat f_r(\psi_c) + r_{V,\Sigma,i}} \ \text{if } |\psi_c - \psi_{s,i}| < 10^{-8}, \qquad E_i = 0 \ \text{if } |\psi_c - \psi_{s,i} - \rho_w g z_i| < 10^{-8} \tag{5}\]
Here \(\rho_w g\) is the gravitational head per metre of height (gravity_head). phylloptim writes the depth of the layer’s midpoint as \(z_i\), which is the \(\bar z_i\) of Section 2, so \(\rho_w g z_i\) is the head that must be overcome to lift water from the midpoint to the collar.
The root vulnerability curve is non-linear in \(\psi\), so the horizontal resistance in Equation 5 is not evaluated at a single potential. It is \(r_{H,\min,i}\) divided by the mean root conductivity across the span between the collar and the layer: \(\Delta\psi_i\) is the width of that span and \(I_i\) the integral of the root vulnerability curve across it, from its lower end \(\psi_{\rm lo}\) to its upper end \(\psi_{\rm hi}\), with conductivity taken as 1 at negative (positive-pressure) potentials. Two special cases are handled exactly rather than with this general form: when \(\psi_c\) equals \(\psi_{s,i}\), the layer is driven by gravity alone; when the potential difference exactly balances the gravitational head, \(E_i = 0\). Only the rooted layers draw water, down to the deepest with root carbon, \(L\). A negative \(E_i\) is a layer gaining water through the roots.
Summing \(E_i\) across the rooted layers gives the total water the root system can supply at a given \(\psi_c\), \(E_{\rm up}\), in kg through the molar mass of water \(M_w\). The model then solves for the root-collar potential and the leaf xylem potential 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 \(\psi_c\) links the soil water balance to leaf-level profit maximisation.
Each plant’s draw from layer \(i\), scaled up from its leaf area, is what the patch removes from that layer: \(u_i\) in Equation 1 is the sum of those draws over every plant in the stand, per unit area of the patch.
Diagnostics: cumulative fluxes
Alongside the \(N\) moisture states, the environment tracks five cumulative auxiliary states (aux_num = 5). 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\);
- cumulative runoff of water pulses, the water a scheduled pulse adds to a layer beyond what the layer can hold. It moves only when a pulse is applied.
Runoff from rain is not accumulated on its own: it is cumulative rainfall less cumulative infiltration and pulse runoff.
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.