Overstorey

Moving cohort refining into C++

Sat, 20 Jun 2026 00:00:00 GMT

plant @develop ad280e9

This post summarises issue #408: moving the SCM’s adaptive cohort-schedule refinement out of R and into C++, and collapsing the surrounding R helpers onto one entry point. The governing constraint was that the FF16 reference baselines stay green at every step — the refactor changes where the work happens, not what it computes.

The problem

The solver carried two intertwined machines smeared across the R/C++ boundary:

A refinement loop that lived mostly in R (build_schedule()). Each iteration constructed a fresh SCM, manually single-stepped it from R to sample a per-node competition (LAI) error during the run, read a per-node reproduction error at the end, flagged nodes whose combined error exceeded schedule_eps, bisected the intervals below them, and repeated.
Reproduction accounting that was already integrated inside the C++ ODE, but was then re-weighted post-hoc — SCM reached back into node_schedule to re-derive each node’s introduction time and re-queried survival_weighting->density(t), even though both values were knowable the moment the node was born.

The only reason the refinement loop was stuck in R was that the competition error had to be sampled during the run as a running maximum across steps — and the R code re-implemented the step loop just to observe it.

The key insight

Every “look it up later” path could be replaced by recording the value on the node at introduction. Once a Node owns its introduction_time and density_at_birth, Species can produce both the weighted-fitness vector and the integration x-axis itself, and SCM no longer needs node_schedule or survival_weighting for any reproduction calculation. With that in place, the running-max competition error can be maintained directly inside SCM::run() — removing the last thing forcing the loop into R.

How it was done — four behaviour-preserving phases

Phase	What moved into C++	Verification
1. Node-level bookkeeping	Nodes stamp their own `introduction_time` + `patch_density_at_birth` at birth; reproduction methods read `species.node_times()` instead of reaching back into `node_schedule`/`survival_weighting`.	Full SCM / strategy / stochastic suites green; no R-facing signatures changed.
2. Error collection in `run()`	A `collect_errors` flag makes `SCM::run()` fold in the per-species running-max competition error; `combined_node_errors()` returns the exact per-node `max(competition, reproduction)` signal the R loop used to assemble.	Asserted bit-exact against the old `run_scm_error()$err$total` for FF16 single / two-species / refined schedules; durable regression test added.
3. Refinement loop + `split_times`	`SCM::refine_schedule()` owns the adaptive loop end-to-end (run → flag → upwind bisection → reset), reusing a single SCM instance.	Reproduces R `build_schedule` exactly (refined times, ODE times, offspring production) for FF16 and K93; durable test added.
4. Breaking API cleanup	One entry point: `run_scm(p, env, ctrl, refine_schedule = FALSE, collect = FALSE, use_ode_times = FALSE)`. `run_scm_collect`, `run_scm_error`, and R-side `build_schedule`/`split_times` removed.	Full suite: 1832 pass, 0 fail, 1 pre-existing skip.

The phasing is the point: phases 1–3 are each independently green and behaviour-preserving, so the numerics never moved. Only phase 4 — the API consolidation — is a deliberate breaking change.

What callers see now

# Refine an adaptive schedule (was: build_schedule(p, ctrl))
p_refined <- run_scm(p, ctrl = ctrl, refine_schedule = TRUE)$parameters

# Run and collect tidied history + reproduction outputs (was: run_scm_collect(x))
out <- run_scm(x, collect = TRUE)

Follow-ups outside this repo

plant.assembly still calls the removed helpers (build_schedule(), run_scm_collect()) in R/community_plant.R and scripts/example/ESA.Rmd. These need the same migration: build_schedule(p, ctrl = ctrl) → run_scm(p, ctrl = ctrl, refine_schedule = TRUE)$parameters, and run_scm_collect(x) → run_scm(x, collect = TRUE).

Note

The FF16 reference baselines in tests/testthat/FF16_reference/ are the safety net for this whole refactor. If any phase had shifted numerics beyond tolerance, that would be a bug — not an expected regeneration.

Making root water uptake fast

Fri, 19 Jun 2026 00:00:00 GMT

plant @develop 81cfeab

This post summarises a sustained performance-engineering effort on the root_water_uptake branch of plant. It is a high-level account of what was achieved and which ideas worked; the blow-by-blow record — every A/B timing, profile, and rejected experiment — lives in the branch’s commit history and in the issues linked below.

What was achieved

In short: the new multi-layer root-water hydraulic solver went from a raw hotspot to a structurally optimised path, roughly an order of magnitude faster end-to-end, with the science held to a tolerance-level shift that moves toward the more accurate reference.

≈4.4× from the algorithmic stack (first working version → end of the early phase): 39.8 s → 9.0 s on the single-species MPL = 10 benchmark, from O(1) spline indexing, transpiration/integral-spline caches, the exact interval-mean conductivity, and int-keyed lookups. The integral-spline cache added a further ≈1.32×, for ≈5–6× by the end of the early phase.
A further ≈2.3× on the hot path afterwards, once each nested root-find was characterised individually and given a superlinear solver where that was provably safe: ≈1.8× (TOMS748 on the inner psi_stem_to_ci solve) × ≈1.2× (TOMS748 on find_root_psi) × ~1.08× (halving the divisions in the per-layer E_from_Soil loop).
~60–75× more accurate inverse hydraulic transform by seeding the integral-spline knots from the closed-form incomplete-gamma integral (issue #468) instead of a trapezoid sum — same hot-path cost, quadrature bias removed at source.
A documented set of rejected levers — global TOMS748, Brent on the outer collar solve, a logistic vulnerability curve, pow(x,2)→x*x, splining the hydraulic cost, loosening the Cᵢ tolerance — each measured, found to be slower / less stable / less accurate, and recorded so they are not re-litigated.
Two safety gates held throughout: every change is bit-identical or its numeric shift is quantified, and every solver swap must still pass the drought-stability scenario (issue #485) with finite output and no NaN.

The model is now considered structurally optimised: ~75% of runtime is the irreducible nested root-find structure, and every bit-identical lever has been taken.

What the model is, and why it was a hotspot

The branch couples three pieces, integrated together by run_scm: a multi-layer soil-water bucket model, a depth-resolved root mass distribution, and a plant hydraulics solver (after Potkay et al. 2021) that finds each individual’s water-stress operating point. The expensive part is the hydraulics: for every individual, at every ODE sub-step, the model solves for the root-collar water potential that maximises profit (assimilation minus hydraulic cost). That solve is two nested root-finds wrapped in an outer optimisation, and each inner evaluation sweeps all soil layers and evaluates vulnerability-curve splines. Profiling consistently put essentially all runtime in this find_root_collar_psi path — a flat profile spread across solver structure and spline evaluation, not memory allocation.

The optimisation phases

Work proceeded through roughly nine phases. The honest pattern: the early algorithmic wins were large; later phases were as much about rejecting plausible-looking levers as landing new ones. A summary of the main levers:

Lever	Outcome
O(1) spline indexing (equidistant-grid arithmetic vs binary search)	Adopted — was the single hottest leaf; bit-identical
Memoised `transpiration()` / integral-spline caches for the per-layer root-vuln integral	Adopted — bit-identical; collapsed ~30 spline evals/call to ~1
Exact interval-mean of root conductivity via a pre-integrated curve	Adopted — fewer evals and more accurate
String-keyed name→index lookups cached as ints; per-time driver memo	Adopted — bit-identical
TOMS748 swapped globally across both nested root-finds	Rejected — produced NaN soil potentials, ran slower
Brent on the outer collar profit-max	Adopted then reverted — its argmax is non-smooth, and the demographic growth gradient needs a smooth operating point; reverted to golden-section search
TOMS748 on the inner `psi_stem_to_ci` solve only	Adopted — target is smooth & monotone; ~1.8×
TOMS748 on the `find_root_psi` solve only	Adopted — brackets provably finite & opposite-sign; ~1.2×
Halve divisions in the `E_from_Soil` per-layer loop	Adopted — `fdiv` latency was the real cost
Spline the xylem hydraulic cost; `pow(x,2)→x*x`; loosen the Cᵢ tolerance	Rejected — slower or no faster, or destabilised the coupled ODE

Two recurring lessons shaped the rejections. First, bisection precision is load-bearing for coupled-ODE stability: loosening the inner Cᵢ tolerance drives a soil layer to zero moisture and trips a drought singularity (issue #485). Second, on Apple-ARM hardware a spline eval already costs about as much as the transcendentals it would replace, so the “spline everything” strategy hit diminishing returns.

Key innovations

Solver choice, split by target. The early blanket rejection of superlinear solvers conflated two different functions. Once each nested root-find was characterised on its own, the inner psi_stem_to_ci solve (smooth, strictly monotone) and the find_root_psi solve (provably finite, opposite-sign brackets) both took TOMS748 safely — converging to the same tolerance in far fewer evaluations. The outer collar optimisation kept golden-section search specifically because its argmax feeds a demographic gradient that must vary smoothly. The single biggest reproducibility constraint throughout: a faster method is only acceptable if it reaches the same answer, not a looser one.

Caching strategy. The cumulative-integral splines (transpiration supply and root vulnerability) are built once per strategy and evaluated O(1) on the hot path, with the per-solve, per-layer integral lookups memoised down to roughly one evaluation per call.

Analytical gamma-integral hydraulic transform (issue #468). The Weibull xylem vulnerability curve has a closed-form integral in terms of the lower incomplete gamma function, . This was verified against independent adaptive quadrature (agreement to ~1e−6 relative) and is now used to seed the integral-spline knots analytically instead of by a running trapezoid sum — same knots, same O(1) hot-path eval, but the quadrature bias removed at the source. The payoff lands on the inverse transform used in simulation: roughly 60–75× more accurate.

Logistic vulnerability curve, evaluated and declined (issue #467). A logistic curve was assessed as a cheaper, AD-friendly alternative. Its forward integral is elementary, but its inverse is not explicit, and for the production stem curve () it biases the transpiration integral by 4–13% — a model change, not a numerical refinement. Recommendation: keep the Weibull for the core; revisit a logistic only in an external calibration/AD context.

Measured outcome

The early algorithmic stack (O(1) splines, memoisation, integral-spline caches, the off-path Brent work) took the model from its first working version to several-fold faster — an end-to-end ≈4.4× was measured on one benchmark build before the later solver work, with further gains from the integral-spline cache. The two newer superlinear-solver wins on the hot path then added roughly 1.8× and 1.2× on the 15-layer scenario, and the E_from_Soil division work a further few percent. Numerically, most adopted changes are bit-identical; the solver swaps and the analytical transform shift results at the tolerance level (sub-percent), and where they move, they move toward the more accurate reference. The model is now considered structurally optimised: ~75% of runtime is the nested root-find structure, and every bit-identical lever has been taken.

Note

This post is pinned to a develop SHA. Absolute timings are machine-specific and deliberately not reproduced here as headline numbers; the durable results are the ratios and the adopted/rejected verdicts. For the full record — exact A/B tables, profiles, and the reasoning behind each rejection — see the root_water_uptake branch history in the plant repository and issues #467 and #468.

A reference prototype for root water uptake

Fri, 19 Jun 2026 00:00:00 GMT

plant @develop 81cfeab

This post preserves the standalone R prototype of the soil→root→stem→leaf hydraulic model that has since been ported to C++ (src/leaf_model.cpp: E_from_Soil_to_Root_Collar, find_root_collar_psi) and wired into the TF24 strategy. It follows Potkay et al. (2021) and is kept as the reference implementation / sanity check for the compiled model. For the consolidated maths see assimilation and hydraulics.

Structure of the prototype:

Geometry & conductances: derive stem (k_sw_max) and leaf (k_l) hydraulic conductances from height/diameter allometry.
Root collar pressure at E = 0: bisection search for the collar potential (P_x_r) where net soil exchange is zero (the wettest feasible point).
Critical root collar pressure: bisection for the collar potential at which the leaf reaches its critical water potential (P_x_l_crit), integrating the pressure drop down the stem and through the leaf in n numerical steps.
Profit curve: sweep P_x_r from the E = 0 point to critical, compute assimilation (Farquhar / Cowan-Farquhar marginal cost) vs hydraulic cost, and pick the profit-maximising operating point.

The Test section at the end cross-checks the compiled Leaf object against this prototype.

Note

The whole prototype is preserved as a readable reference. The chunks that load the prototype’s helper functions, run the numerical solves, and validate against the compiled Leaf are set to #| eval: false — they depend on machine-specific source() paths and the compiled object, and would be slow. The code is intact so it can be re-run after fixing those paths and building plant.

The prototype sources its helper functions (E_from_Soil_to_Root_Collar, the vulnerability curves VC_l/VC_sw/VC_r) from a working copy of plant. The original paths point at a different machine and must be edited to run, so this chunk is not executed.

rm(list=ls())

source("/Users/z3533545/Documents/GitHub/plant/R/leaf.R")
source("/Users/z3533545/Documents/GitHub/plant/R/root_uptake.R")

H = 5.44 # Height (m)
LA = 1 # Leaf area (m^2)
n = 20 # n steps for numerical integration

b2 = 9.3e-1 # Power-law scaling coefficient for stem xylem conductance (mol H2o s^-1 MPa^-1)
c2 = 0.93 # Exponent for power-law scaling of stem conductance
D_ref = 1 # Reference diameter (m)?
b0 = 64.6; # Power-law scaling coefficient for height (m)
c0 = 0.6411 # Exponent for power-law scaling of height (unitless)
D = D_ref * (H/b0)^(1/c0) # Diameter (m)?
D_hw = D*0.5 # Heartwood diameter (m)?

# got from supps in Potkay et al. (2021)
k_sw_max = b2 * (D / D_ref) ^ c2 * (1 - (D_hw / D) ^ (c2/c0 + 1))

# Psi soil for layers starting from the top
P_soil = c(-0.06,-0.12) # MPa

# Depth of middle of layer
z_soil_mid = c(0.05,0.15) # m

# Find the minimum (driest soil layer)
P_s_min = min(P_soil)

# Find the depth of the driest soil layer
z_P_s_min = z_soil_mid[P_soil == P_s_min]

# If the are multiple layers which are equally driest, define it as the deepest one
z_P_s_min = max(z_P_s_min)

# Find the depth of the driest soil layer
P_s_max = max(P_soil)

# Find the depth of the wettest soil layer
z_P_s_max = z_soil_mid[P_soil == P_s_max]

# If the are multiple layers which are equally wettest, define it as the deepest one
z_P_s_max = max(z_P_s_max)

# Start defining the boundary conditions for the bisection search for the optimum root collar pressure (P_x_r)

# The upper value (i.e. least negative value) is equal to the wettest soil layer
P_x_r_UB_0 = P_s_max

# Density of water
rho = 1e3 #kg m^-3

# Acceleration due to gravity
g = 9.8 # m s^-2

# The lower boundary value of root collar pressure (i.e most negative) which is equivalent to the driest soil layer minus the gravitational potential
P_x_r_LB_0 = P_s_min - rho * g * z_P_s_min / 1e6

# If the intial boundary values too narrow (diff < 1), make the difference equal to one

if(abs(P_x_r_LB_0 - P_x_r_UB_0) < 1){
    P_x_r_LB_0 = P_x_r_UB_0 - 1
}

# Find the middle root collar pressure between the two boundaries

P_x_r_M_0 = (P_x_r_UB_0 + P_x_r_LB_0) / 2

# Set up a vector of root collar pressure

P_x_r_3_0 = c(P_x_r_UB_0, P_x_r_M_0, P_x_r_LB_0)

# Create a vector of transpiration values

E_3_0 = rep(0,3)

# While loop continues until transpiration vector includes a negative and a positive value

while((length(E_3_0[E_3_0 < 0]) == 0) +
      (length(E_3_0[E_3_0 > 0]) == 0) > 0){

  # iterate across the three root collar values
  for(i in 1:length(P_x_r_3_0)){

    # start with upper boundary first, through to lower

    P_x_r_i = P_x_r_3_0[i]

    # calculate soil to root transpiration value for a given root collar psi
    E_3_0[i] <- E_from_Soil_to_Root_Collar(P_x_r_i, P_soil = P_soil, rho = rho, g = g)[[1]]
  }

  # If no negative transpiration values then increase upper boundary root collar psi by an increment
  if(length(E_3_0[E_3_0 <0]) == 0){
    P_x_r_3_0[1] = P_x_r_3_0[1] + 0.1;
  }

  # If no postive transpiration values then decrease lower boundary root collar psi by an increment
  if(length(E_3_0[E_3_0 >0]) == 0){
    P_x_r_3_0[3] = P_x_r_3_0[3] - 0.1;
  }

  # Define new midsection root collar value
  P_x_r_3_0[2] = (P_x_r_3_0[1] + P_x_r_3_0[3]) / 2;
}

# Set i at 0 (iterator for bisection search below)
i = 0

# Iterate until dP_x_r_3_0 brought within tolerance (1e-3)

# This bisection is to find the root collar pressure when transpiration equals zero
while(abs(range(P_x_r_3_0)[1]-range(P_x_r_3_0)[2]) > 1e-3){

  i = i + 1;

  # Stop if iteration goes too long
  if(i > 100){
    print("error")
    stop()
  }

  # Must have a negative and positive value, if not stop
  if(length(E_3_0[E_3_0 < 0]) == 0){
        stop()
  } else if(length(E_3_0[E_3_0 > 0]) == 0){
        stop()
  }



  # Find the upper bound of transpiration in iteration, i.e. highest positive value
  E_UB_0 = max(E_3_0[E_3_0 < 0]);

  # Find the lower bound of transpiration in iteration, i.e. lowest negative value
  E_LB_0 = min(E_3_0[E_3_0 > 0]);

 # Root collar xylem pressures that correspond to ZERO transpiration rates
    P_x_r_UB_0 = P_x_r_3_0[E_3_0 == E_UB_0];
    P_x_r_UB_0 = max(P_x_r_UB_0);
    P_x_r_LB_0 = P_x_r_3_0[E_3_0 == E_LB_0];
    P_x_r_LB_0 = min(P_x_r_LB_0);
    # Mid-point for bisection
    P_x_r_M_0 = (P_x_r_UB_0 + P_x_r_LB_0) / 2;

  # Reconstruct range

    P_x_r_3_0_new = c(P_x_r_UB_0, P_x_r_M_0, P_x_r_LB_0);

  # If reconstructed range is same as original, stop

  if(sum(P_x_r_3_0_new == P_x_r_3_0) == 3){
    stop()
  }

  # Find E based on middle of root collar psi range

  P_x_r_3_0 = P_x_r_3_0_new;

  E_3_0 = c(E_UB_0, NA, E_LB_0)

  P_x_r_i = P_x_r_3_0[2];

  E_i = E_from_Soil_to_Root_Collar(P_x_r_i, P_soil = P_soil, rho = rho, g = g)[[1]]

  E_3_0[2] = E_i

  }

# Numerical soluution means that E_0 may not be perfectly zero, find the smallest postive E value
E_0 = min(E_3_0[E_3_0 > 0])

# Find the root collar pressure associated with the smallest positive E value
P_x_r_0 = P_x_r_3_0[E_3_0 == E_0];
# If multiple root collar associated with that E, choose the most negative
P_x_r_0 = min(P_x_r_0);

# Initialise a critical leaf water potential value, it will become more negative by iterating the vulnerarbility curve below
P_x_l_crit = -1

# Iterate P_x_l_crit increasingly negative until the fraction of conductance is 0.001, very low fracution
while(VC_l(P_x_l_crit) > (1 - 0.999)){
    P_x_l_crit = P_x_l_crit - 0.1;
}

# inital guesses for upper and lower bounds of critical root collar pressure for bisection method

# the upper bound is the value at which transpiration is = 0

# the lower bound is the critical leaf water potential
P_x_r_UB_crit = P_x_r_0;
P_x_r_LB_crit = P_x_l_crit;
P_x_r_M_crit = (P_x_r_LB_crit + P_x_r_UB_crit) / 2;

P_x_r_3_crit = c(P_x_r_UB_crit, P_x_r_M_crit, P_x_r_LB_crit);
P_x_l_3_crit = rep(NA,3);

k_l = 1.6e-2

for(i in 1:3){
  P_x_r_i = P_x_r_3_crit[i];
  E_i = E_from_Soil_to_Root_Collar(P_x_r_i, P_soil = P_soil, rho = rho, g = g)[[1]]

  P_x_l_i = P_x_r_i;

  for(j in 1:n){
    P_x_l_i = P_x_l_i - rho * g * (H / n) / 1e6 - (E_i * LA) / (n * k_sw_max * VC_sw(min(0, P_x_l_i)));
  }

    for(j in 1:n){
    P_x_l_i = P_x_l_i - E_i/(n*k_l*VC_l(min(0, P_x_l_i)));
  }

  P_x_l_3_crit[i] = P_x_l_i

  }

i = 0;

while(abs(range(P_x_r_3_crit)[1]-range(P_x_r_3_crit)[2]) > 1e-3){

  i = i + 1;

    if(i > 100){
    print("error")
    stop()
    }

  F_value = P_x_l_crit - P_x_l_3_crit; #objective function, F -- we seek to find that P_x_r that makes F equal to zero

    F_UB = max(F_value[F_value < 0]);
    F_UB = F_UB[1];
    F_LB = min(F_value[F_value > 0]);
    F_LB = F_LB[1];

  P_x_r_UB_crit = P_x_r_3_crit[F_value == F_UB];
  P_x_r_UB_crit = P_x_r_UB_crit[1];

  P_x_r_LB_crit = P_x_r_3_crit[F_value == F_LB];
  P_x_r_LB_crit = P_x_r_LB_crit[1];

P_x_r_M_crit = (P_x_r_LB_crit + P_x_r_UB_crit) / 2;

P_l_UB_crit = P_x_l_3_crit[P_x_r_3_crit == P_x_r_UB_crit];
P_l_LB_crit = P_x_l_3_crit[P_x_r_3_crit == P_x_r_LB_crit];


  P_x_r_3_crit = c(P_x_r_UB_crit, P_x_r_M_crit, P_x_r_LB_crit);
    P_x_l_3_crit = c(P_l_UB_crit, NA, P_l_LB_crit);

  P_x_r_i = P_x_r_3_crit[2];

    E_i = E_from_Soil_to_Root_Collar(P_x_r_i, P_soil = P_soil, rho = rho, g = g)[[1]]

      P_x_l_i = P_x_r_i;

      for(j in 1:n){
        P_x_l_i = P_x_l_i - rho * g * (H / n) / 1e6 - (E_i * LA) / (n * k_sw_max * VC_sw(min(0, P_x_l_i)));
      }

      for(j in 1:n){
              P_x_l_i = P_x_l_i - E_i / (n * k_l * VC_l(min(0, P_x_l_i)));

      }

      P_x_l_3_crit[2] = P_x_l_i;

}

P_x_r_crit = min(P_x_r_3_crit[P_x_l_3_crit > -Inf]);

P_x_r = seq(P_x_r_0, P_x_r_crit, length.out = 50);
P_x_s = rep(NA, length(P_x_r))
P_x_l = rep(NA, length(P_x_r))
E = rep(NA, length(P_x_r))
E_soil = matrix(NA, nrow = 2, ncol = length(P_x_r));
r_R_H = matrix(NA, nrow = 2, ncol = length(P_x_r));
r_R_V = matrix(NA, nrow = 2, ncol = length(P_x_r));
f_r = matrix(NA, nrow = 2, ncol = length(P_x_r));

for(i in 1:length(P_x_r)){
  P_x_r_i = P_x_r[i];

  res = E_from_Soil_to_Root_Collar(P_x_r_i, P_soil = P_soil, rho = rho, g = g)

  E[i] = res[[1]]
  E_soil[1:2, i] = res[[2]];
  r_R_H[1:2, i] = res[[3]];
  r_R_V[1:2, i] = res[[4]];
  f_r[1:2, i] = res[[5]];

  P_x_s_i = P_x_r_i;

   for(j in 1:n){
        P_x_s_i = P_x_s_i - rho * g * (H / n) / 1e6 - (E_i * LA) / (n * k_sw_max * VC_sw(min(0, P_x_l_i)));
   }

  P_x_s[i] = P_x_s_i;

  P_x_l_i = P_x_s_i;

    for(j in 1:n){
        P_x_l_i = P_x_l_i - E_i / (n * k_l * VC_l(min(0, P_x_l_i)));
    }

  P_x_l[i] = P_x_l_i;
}

T_a = 25

T_l = T_a * rep(1, length(P_x_l)); #in [C] -- assuming leaf temperature equals air temperature

satur_mol_fract_air = (-0.0043 + 0.01 * exp(0.0511 * T_a)); #saturated mole fraction of vapor in air [kPa]
satur_mol_fract_leaf = (-0.0043 + 0.01 * exp(0.0511 * T_l)); #saturated mole fraction of vapor in leaf [kPa]
RH = min(0.5, 0.99);
VPD_air = (1 - RH) * 0.61094 * exp(17.625* T_a / (T_a + 243.04)); #air-to-air vapor pressure deficit [kPa]
VPD_l = satur_mol_fract_leaf - satur_mol_fract_air + VPD_air; #leaf-to-air vapor pressure deficit in kPa
VPD_l = pmax(0, VPD_l);

atm_kpa = 101.3

# Interpreting stomatal conductances, G_w and G_c
G_w = abs(E*atm_kpa / VPD_l); #stomatal conductance to vapor [mol H2O * m^-2 * s^-1]
G_w[E == 0] = 0;
G_w = pmax(0, G_w);
G_c = G_w / 1.6; #stomatal conductance to CO2 [mol CO2 * m^-2 * s^-1]

# Interpreting stomatal conductances, G_w and G_c
G_w = abs(E / VPD_l); #stomatal conductance to vapor [mol H2O * m^-2 * s^-1 * kPa^-1]
G_w[E == 0] = 0;
G_w = pmax(0, G_w);
G_c = G_w / 1.6; #stomatal conductance to CO2 [mol CO2 * m^-2 * s^-1 * kPa^-1]

V_cmax = 100*1e-6
J_max = 167*1e-6
R_abs = 1000
var_kappa = 6.9e-7
J_phi = var_kappa * R_abs; #var_kappa is proportionality constant between J and R_abs in [mol CO2 * J^-1]
c_prime2 = 0.97
J = (J_max + J_phi - ((J_max + J_phi)^ 2 - 4 * c_prime2 * J_max * J_phi)^ 0.5) / (2 * c_prime2); #hyperbolic minimum of J_max and J_phi with curvature of 0.9
Gamma_star = 36e-6 * 101.325; #in [kPa]
K_c = 275e-6 * 101.325; #in [kPa]
K_o = 420000e-6 * 101.325; #in [kPa]
R_d = 0.01 * V_cmax; #leaf dark respiration in [mol CO2 * m^-2 * s^-1]

#Eller et al. (2019; SOX appendix)
o_a = 21
# Gamma_star = 42.75
c_a = 410e-6 * 101.325

a_c = V_cmax;
a_j = J / 4;
b_c = K_c * (1 + o_a / K_o);
b_j = 2 * Gamma_star;
beta_c = (R_d - a_c) - G_c * (c_a + b_c);
beta_j = (R_d - a_j) - G_c * (c_a + b_j);
gamma_c = a_c * (c_a - Gamma_star) - R_d * (c_a + b_c);
gamma_j = a_j * (c_a - Gamma_star) - R_d * (c_a + b_j);

A_c = -beta_c / 2 - ((beta_c / 2)^2 - gamma_c * G_c)^0.5;
A_j = -beta_j / 2 - ((beta_j / 2)^2 - gamma_j * G_c)^ 0.5;
# A_j = real(A_j);

# correct for if G_c == inf, in which case c_i = c_a
A_c[G_c == Inf] = a_c[G_c == Inf]* (c_a - Gamma_star[G_c == Inf]) / (c_a + b_c[G_c == Inf]) - R_d[G_c == Inf];
A_j[G_c == Inf] = a_j[G_c == Inf] * (c_a - Gamma_star[G_c == Inf]) / (c_a + b_j[G_c == Inf]) - R_d[G_c == Inf];

#calculate photosynthesis by hyperbolic-minimum

c_prime1 = 0.97

A_n = (A_c + A_j - ((A_c + A_j)^2 - 4 * c_prime1 * A_c * A_j)^ 0.5) / (2 * c_prime1); #net carbon assimilation rate [mol CO2 * m^-2 * s^-1]

# determine dA_n/dR_abs by chain-rule, assuming negligle effect of
# electron-transport rate, J, on stomatal conductance, G_c (derrived
# assuming dG_c/dJ = 0)
dA_n_dA_c = (1 - ((A_c + (1 - 2 * c_prime1) * A_j) / ((A_c + A_j)^ 2 - 4 * c_prime1 * A_c * A_j)^ 0.5)) / (2 * c_prime1);
dA_n_dA_j = (1 - ((A_j + (1 - 2 * c_prime1) * A_c) / ((A_c + A_j)^ 2 - 4 * c_prime1 * A_c * A_j)^ 0.5)) / (2 * c_prime1);
var_H = (J/4 + G_c * (c_a + 2 * Gamma_star) - R_d) / 2;
#inv_Ohm = J/4 .* (c_a - Gamma_star) - R_d .* (c_a + 2 * Gamma_star);
dA_j_dJ = (1 / 8) * (G_c * (c_a - Gamma_star)) / (var_H - A_j);
dA_j_dJ[G_c == Inf] = 1/4 * (c_a - Gamma_star[G_c == Inf]) / (c_a + b_j[G_c == Inf]);
dJ_dJ_phi = (1 - ((J_phi + (1 - 2 * c_prime2) * J_max) / ((J_max + J_phi)^ 2 - 4 * c_prime2 * J_max * J_phi)^ 0.5)) / (2 * c_prime2);
dJ_phi_dR_abs = var_kappa;
dA_n_dR_abs = dA_n_dA_j * dA_j_dJ * dJ_dJ_phi * dJ_phi_dR_abs;

#determine Cowan & Farquhar's (1977) marginal cost (lambda), dA_n/dE, by finite-difference
c_i = c_a - A_n / G_c;
# dA_c_dc_i = a_c .* (Gamma_star + b_c) ./ (c_i + b_c).^2;
# dA_j_dc_i = a_j .* (Gamma_star + b_j) ./ (c_i + b_j).^2;
# x = dA_n_dA_c .* dA_c_dc_i + dA_n_dA_j .* dA_j_dc_i; %%% dA_n_dc_i
# dA_n_dE = A_n ./ E .* x ./ (x + G_c); %%%Eq. 4 in Buckley et al. (2016) "Optimal Plant Water Economy"

f_sw = LA * E / (P_x_r - P_x_s - rho * g * H / 10^6) / k_sw_max; #%[unitless]
f_sw[1] = mean(pmin(1, VC_sw(seq(P_x_r[1], P_x_s[1], length.out = 10)))); #different defintion since first value represents where E = 0
f_l =  E / (P_x_s - P_x_l) / k_l; #[unitless]
f_l[1] = min(1, VC_l(min(0, P_x_s[1]))); #different defintion since first value represents where E = 0

dP = 1e-2;
dVC_r_dP_x_r = (VC_r(pmin(0, P_x_r + dP)) - VC_r(pmin(0, P_x_r))) / dP;
dVC_r_dP_soil = (VC_r(pmin(0, P_soil + dP)) - VC_r(pmin(0, P_soil))) / dP;
dVC_r_dP_soil = matrix(dVC_r_dP_soil, 1, length(P_x_l)*length(dVC_r_dP_soil));
d2VC_r_dP_soil2 = (VC_r(pmin(0, P_soil + dP)) + VC_r(pmin(0, P_soil - dP)) - 2 * VC_r(min(0, P_soil))) / dP^2;
d2VC_r_dP_soil2 = matrix(d2VC_r_dP_soil2, 1, length(P_x_l)*length(d2VC_r_dP_soil2));

df_r_dP_x_r = (f_r - VC_r(pmin(0, P_x_r))) / (P_soil - P_x_r); #in [MPa^-1]
df_r_dP_x_r[abs(P_x_r - P_soil) < 1e-2] = (1/2) * dVC_r_dP_soil[abs(P_x_r - P_soil) < 1e-2]; #needs to be corrected where P_x_r = P_soil
d2f_r_dP_x_r2 = (2*df_r_dP_x_r - dVC_r_dP_x_r) / (P_soil - P_x_r); #in [MPa^-2]
d2f_r_dP_x_r2[abs(P_x_r - P_soil) < 1e-1] = (1/3) * d2VC_r_dP_soil2[abs(P_x_r - P_soil) < 1e-1]; #needs to be corrected where P_x_r = P_soil

df_sw_dP_x_s = (f_sw - VC_sw(pmin(0, P_x_s))) / (P_x_r - P_x_s); #in [MPa^-1]
df_sw_dP_x_r = (VC_sw(pmin(0, P_x_r)) - f_sw) / (P_x_r - P_x_s); #in [MPa^-1]

r_R_V_sum = r_R_V

for(i in 1:ncol(r_R_V)){
  r_R_V_sum[,i] = cumsum(r_R_V[,i])
}

r_R = r_R_H + r_R_V_sum;

a_var = 1 - LA * E / (f_sw^2) / k_sw_max * df_sw_dP_x_s;
b_var = 1 + LA * E / (f_sw^2) / k_sw_max * df_sw_dP_x_r;
c_var = apply((1/LA - E_soil * r_R_H / f_r * df_r_dP_x_r) / r_R, MARGIN = 2, FUN = sum);
d_var = VC_l(pmin(0, P_x_s)) / f_l;
e_var = VC_l(pmin(0, P_x_l)) / f_l;

k_c = e_var / (1/f_l/k_l + d_var/a_var*(b_var/c_var + LA/f_sw/k_sw_max));

c0 = c_var[1];
i = (1:length(c_var))[(c_var - c0) == min(abs(c_var - c0))]

P_x_r0 = P_x_r[i];
f_sw0 = f_sw[i];
f_r0 = f_r[,i];
df_r0_dP_x_r0 = df_r_dP_x_r[,i];
d2f_r0_dP_x_r0 = d2f_r_dP_x_r2[,i];

P_x_l0 = P_x_r0 - rho*g*H/1e6;
f_l0 = VC_l(pmin(0, P_x_l0));

E_soil0 = E_soil[,i];
r_R0 = r_R[,i];
r_R_H0 = r_R_H[,i];
r_R_V0 = r_R_V[,i];

c_r_H = c(20,30)
c_r_V = c(20,30)
## CHECK
dP_x_r0_dc_r_H = 1 / c0 / c_r_H * E_soil0 *r_R_H0 / r_R0;
dP_x_r0_dc_r_V = 1 / c0 / c_r_V * cumsum((E_soil0* r_R_V0 / r_R0)[length(E_soil0* r_R_V0 / r_R0):1]);

k_cmax = 1 / (1/k_l/f_l0 + 1/c0 + LA/f_sw0/k_sw_max)

df_l0_dP_x_r0 = (VC_l(min(0, P_x_l0 + dP)) - VC_l(min(0, P_x_l0))) / dP; #calculated in a finite-difference approach
df_l0_dH = - rho*g/1e6 * df_l0_dP_x_r0;
df_sw0_dP_x_r0 = (VC_sw(min(0, P_x_r0)) - VC_sw(min(0, P_x_l0))) / (rho*g*H/1e6);
df_sw0_dH = (VC_sw(min(0, P_x_l0)) - f_sw0) / H;

c0 = 0.64
c1 = 0.63
dH_dD = c0 * H / D;
dW_dD = c1 * W / D;
W = 1
D_hw = 0.08
dk_sw_max_dD = k_sw_max / D * (c2 + (c2/c0 + 1 - c2) * (D_hw / D) ^ (c2/c0 + 1)) / (1 - (D_hw / D) ^ (c2/c0 + 1));

dk_cmax_dD = k_cmax^2 * ((df_l0_dH/k_l/(f_l0^2) + LA*df_sw0_dH/k_sw_max/(f_sw0^2))*dH_dD +
             LA/(k_sw_max^2)/f_sw0*dk_sw_max_dD);
dk_cmax_dLA = k_cmax^2 * (1/k_sw_max/f_sw0 - 1/(c0^2*LA^2)*sum(1/r_R0));

# at E = E_max
P_x_lcrit = min(P_x_l[P_x_l > -Inf]);
A_nmax = A_n[P_x_l == P_x_lcrit];
E_max = E[P_x_l == P_x_lcrit];
dA_n_dE_crit = dA_n_dE[P_x_l == P_x_lcrit];
dA_n_dR_abs_crit = dA_n_dR_abs[P_x_l == P_x_lcrit];

G_wmin = 0

if(A_nmax > 0){
    F_value = A_n / A_nmax + k_c / k_cmax;
    dF_dP_l = diff(F_value) / diff(P_x_l);
    i = 0
    while(i < length(dF_dP_l)){

      i = i + 1;

        if(i >= length(dF_dP_l)){
            error('ERROR')
        }

      if(dF_dP_l[i] >= 0){
        if(G_w[i] >= G_wmin){
          break
        }
      }

    }
}

P_x_l = P_x_l[i];
P_x_s = P_x_s[i];
P_x_r = P_x_r[i];

Test

This section cross-checks the compiled Leaf object against the prototype. It depends on a local build of plant (devtools::load_all), the compiled Leaf class, and the prototype state computed above, so every chunk is left unevaluated.

library(plant)
library(ggplot2)
library(dplyr)
library(tidyr)
library(purrr)
library(patchwork)

devtools::load_all(".")

sw <- list(
  vcmax_25 = 100,                  #  umol m^-2 s^-1
  c = 2.680147,                  # unitless
  b = 3.898245,                  # -MPa
  psi_crit = 5.870283,           # -MPa
  beta1 = 20000,                 # hydraulic cost for Bartlett method umol m^-3 s^-1
  beta2 = 1.5,                   # exponent for effect of hydraulic risk  (unitless)
  jmax_25 = 157.44,              #  maximum electron transport rate umol m^-2 s^-1
  hk_s = 4,                      # maximum hydraulic-dependent sapwood turnover rate yr ^ -1
  a = 0.30,                      # quantum yield of photosynthetic electron transport  (mol mol^-1)
  curv_fact_elec_trans = 0.7,    # curvature factor for the light response curve  (unitless)
  curv_fact_colim = 0.99,        # curvature factor for the colimited photosythnthesis equatiom
  GSS_tol_abs = 1e-3,            #  ???
  vulnerability_curve_ncontrol = 100,  # ????
  ci_abs_tol = 1e-3,             # ???
  ci_niter = 1000
)

leaf <- Leaf(vcmax= sw$vcmax_25, b = sw$b, c = sw$c, psi_crit = sw$psi_crit,
             beta2 = sw$beta2, jmax_25 = sw$jmax_25, hk_s = sw$hk_s, a = sw$a, curv_fact_elec_trans = sw$curv_fact_elec_trans, curv_fact_colim = sw$curv_fact_colim, GSS_tol_abs = sw$GSS_tol_abs, vulnerability_curve_ncontrol = sw$vulnerability_curve_ncontrol, ci_abs_tol = sw$ci_abs_tol, ci_niter = sw$ci_niter, g1_TF24 = 46.32995)

tibble(psi_r = seq(-0.06,-3.30,-0.01)) %>%
mutate(E = purrr::map_dbl(psi_r,
    ~E_from_Soil_to_Root_Collar(.x, P_soil = P_soil, rho = rho, g = g)[[1]])) -> psi_r_E

psi_r_E %>%
  ggplot(aes(x = psi_r, y = E)) +
  geom_point()

find_psi_leaf_from_root <- function(psi_root, E){
  leaf$set_physiology(PPFD = 1000, psi_soil = psi_root, soil_moist = 0.01, leaf_specific_conductance_max = k_sw_max, atm_vpd = 2, ca = 40, sapwood_volume_per_leaf_area = 1.8e-04, rho = 608, a_bio = 0.0245, leaf_temp = 25, atm_o2_kpa = 21, atm_kpa = 101.3)
  psi_stem = leaf$transpiration_to_psi_stem(E/kg_2_mol_h20)
  psi_stem = leaf$transpiration_to_psi_stem(E)
  leaf$set_leaf_states_rates_from_psi_stem(psi_stem)
  ci_ = leaf$ci_
  assim_colimited_ = leaf$assim_colimited_
  hydraulic_cost_TF = leaf$hydraulic_cost_TF(psi_stem)

    P_x_l_i = -psi_root;

  n_i = 50
    for(j in 1:n_i){
    # P_x_l_i = P_x_l_i - E/(n_i*k_sw_max*((leaf$proportion_of_conductivity(psi = -P_x_l_i) +
    #                                        leaf$proportion_of_conductivity(psi = -(P_x_l_i- E/(n_i*k_sw_max*(leaf$proportion_of_conductivity(psi = -P_x_l_i)))))/2)));
    #
        P_x_l_i = P_x_l_i - E/(n_i*k_sw_max*((leaf$proportion_of_conductivity(psi = -P_x_l_i))));
  }





  return(list(P_x_l_i= P_x_l_i,
              psi_stem = psi_stem,
              assim_colimited_ = assim_colimited_,
              hydraulic_cost_TF = hydraulic_cost_TF))
}

psi_r_E %>%
  slice(1:324) %>%
  mutate(psi_l = map2(psi_r, E, ~find_psi_leaf_from_root(-.x, .y)))%>%
  unnest_wider(psi_l) -> psi_r_l_E

psi_r_l_E %>%
  mutate(psi_stem = -psi_stem) %>%
  mutate(P_x_l_i = P_x_l_i) %>%
  mutate(psi_root_collar = psi_r) %>%
  mutate(psi_soil_1 = -0.06) %>%
  mutate(psi_soil_2 = -0.12) %>%
  pivot_longer(cols = c(psi_soil_1, psi_soil_2, psi_root_collar, psi_stem, P_x_l_i)) %>%
  ggplot(aes(y = value, x = E)) +
  geom_point(aes(colour = name, group = name)) +
  # geom_vline(xintercept = 0.00320) +
  ylab("psi") +
  theme_bw()-> a

psi_r_l_E %>%
  mutate(profit = assim_colimited_ - hydraulic_cost_TF) %>%
  mutate(E_max_profit = ifelse(profit == max(profit), E, NA)) %>%
  pivot_longer(cols = c(profit,hydraulic_cost_TF, assim_colimited_)) %>%
  ggplot(aes(y = value, x = E)) +
  geom_point(aes(colour = name, group = name))+
  geom_vline(aes(xintercept = E_max_profit)) +
  ylab("Carbon inputs and outputs") +
  theme_bw()-> b

a/b

find_psi_leaf_from_root <- function(psi_root, E){
  leaf$set_physiology(PPFD = 1000, psi_soil = psi_root, leaf_specific_conductance_max = 4.8e-05, atm_vpd = 2, ca = 40, sapwood_volume_per_leaf_area = 1.8e-04, rho = 608, a_bio = 0.0245, leaf_temp = 25, atm_o2_kpa = 21, atm_kpa = 101.3)

   P_x_l_i = psi_root;

    for(j in 1:n){
        P_x_l_i = P_x_l_i - rho * g * (H / n) / 1e6 - (E * LA) / (n * k_sw_max * VC_sw(min(0, P_x_l_i)))
    }

    for(j in 1:n){
        P_x_l_i = P_x_l_i - E / (n * k_l * VC_l(min(0, P_x_l_i)))
    }
}

solve_root_crit <- function(){
  tibble(psi_r = seq(P_x_r_UB_crit,-sw$psi_crit,length.out = n)) %>%
  mutate(root_E = map_dbl(psi_r, ~E_from_Soil_to_Root_Collar(.x, P_soil = P_soil, rho = rho, g = g)[[1]])) -> res

  res$transpiration_leaf <- c()

  for(i in 1:n){
      leaf$set_physiology(PPFD = 1000, psi_soil = -res$psi_r[i], leaf_specific_conductance_max = k_sw_max, atm_vpd = 2, ca = 40, sapwood_volume_per_leaf_area = 1.8e-04, rho = 608, a_bio = 0.0245, leaf_temp = 25, atm_o2_kpa = 21, atm_kpa = 101.3)

    res$transpiration_leaf[i] <- leaf$transpiration(psi_stem = sw$psi_crit)

  }
      return(res)
}

# Solve the critical root pressure (i.e. the root pressure at which leaf crit is reached and E = E)

solve_root_crit() %>%
  mutate(diff = root_E - transpiration_leaf) %>%
  filter(abs(diff) == min(abs(diff))) %>%
  pull(psi_r) -> root_crit

psi_r_E %>%
  mutate(psi_l = map2_dbl(psi_r, E, ~find_psi_leaf_from_root(-.x, .y)))

tibble(psi_r = seq(P_x_r_UB_crit,root_crit,-0.01)) %>%
mutate(E = purrr::map_dbl(psi_r,
    ~E_from_Soil_to_Root_Collar(.x, P_soil = P_soil, rho = rho, g = g)[[1]])) -> psi_r_E

psi_r_E %>%
  ggplot(aes(x = psi_r, y = E)) +
  geom_point()

psi_r_E %>%
  # slice(1:76) %>%
  mutate(psi_l = map2(psi_r, E, ~find_psi_leaf_from_root(-.x, .y)))%>%
  unnest_wider(psi_l) -> psi_r_l_E

psi_r_l_E %>%
  mutate(psi_stem = -psi_stem) %>%
  mutate(P_x_l_i = P_x_l_i) %>%
  mutate(psi_root_collar = psi_r) %>%
  mutate(psi_soil_1 = -0.06) %>%
  mutate(psi_soil_2 = -0.12) %>%
  pivot_longer(cols = c(psi_soil_1, psi_soil_2, psi_root_collar, psi_stem, P_x_l_i)) %>%
  ggplot(aes(y = value, x = E)) +
  geom_point(aes(colour = name, group = name)) +
  # geom_vline(xintercept = 0.00320) +
  ylab("psi") +
  theme_bw()-> a

psi_r_l_E %>%
  mutate(profit = assim_colimited_ - hydraulic_cost_TF) %>%
  pivot_longer(cols = c(profit,hydraulic_cost_TF, assim_colimited_)) %>%
  ggplot(aes(y = value, x = E)) +
  geom_point(aes(colour = name, group = name))+
  # geom_vline(xintercept = 0.00320) +
  ylab("Carbon inputs and outputs") +
  theme_bw()-> b

a/b

Reviewing the TF24 leaf model code

Fri, 19 Jun 2026 00:00:00 GMT

plant @develop 81cfeab

This post summarises a structural code review of the two core TF24 hydraulics sources in plant: src/leaf_model.cpp (the plant hydraulic solver) and src/tf24_strategy.cpp (the strategy/allocation layer that drives it). The review targeted structure, clarity, and maintainability rather than new science — with speed called out only where existing profiling supported it.

Because both files sit on a numerically sensitive hot path, the governing constraint throughout was that every accepted change be validated bit-identically against HEAD (or its trajectory shift quantified) before being considered done. The headline result: eleven findings resolved, the science provably unchanged.

What changed, by class of finding

Class	What was addressed	Outcome
Caching redundant work	Temperature/O2-dependent photosynthesis params recomputed every `set_physiology` call	Cached on `(leaf_temp_, atm_o2_kpa_)`; bit-identical, speed-neutral, kept for clarity
Heap-allocation reuse	Per-call `mass_root_prop_` vector allocated in `net_mass_production_dt`	Promoted to a reused member buffer; hygiene, not a measured speed win
Redundant builders (DRY)	`setup_transpiration` / `setup_root_vulnerability` duplicated the knot-grid + gamma cumulative-integral build	Factored into a shared `build_cumulative_vulnerability_integral` helper
Duplicated logic	Triple-inlined “shut down at psi_crit” early-exit in `find_root_collar_psi`	Extracted `set_shutdown_state(...)` helper
Variable shadowing	Local `hydraulic_cost_` shadowing the member in `profit_psi_stem_*`	Renamed locals to `cost`
Magic constants	Hard-coded root-distribution numbers and a duplicated unit factor	Named file-scope constants; unit factor documented and left inline (FP rounding)
Unit divergence	`E_up_` in kg vs per-layer consumption in mol	Named `kg_per_mol_h2o`; intentional divergence documented at both sites
Sign conventions	`root_collar_psi_` and `opt_psi_stem_` flipped sign by code path	Made sign-consistent across all branches; diagnostic-only change
Naming / hygiene	`soil_depth` arg that was really a layer index; signed/unsigned loop comparison; truncated comment	Renamed to `soil_layer`, loop types aligned, comment completed

Two further items from the original log were resolved by being rejected or deferred on profiling grounds — the hydraulic_cost_TF inner-loop exp/pow and the isfinite guards in the transport hot loop — and are tracked in the companion performance notes rather than here.

Key takeaways

Bit-identical was the bar, not a bonus. Most changes were proven exact by construction (same arithmetic, same accumulation order). Where a change would have reordered a floating-point summation — collapsing the 60*60*12*365 unit product, or moving a kg conversion inside a per-layer loop — it was deliberately not made, because the adaptive ODE amplifies the rounding difference. Documenting why something stays “ugly” turned out to be as valuable as cleaning it up.
The sign-convention fix was the only correctness finding. The apparent transpiration / transpiration_to_psi_stem discrepancy was confirmed not a bug — two domain-natural conventions, internally consistent. The genuine defect was diagnostic aux columns (root_collar_psi_, opt_psi_stem_) that stored signed-negative vs positive-magnitude potentials depending on code path. These are written out but never read back into any rate, so the fix is diagnostic-only — every driver column verified max|Δ| = 0.
“Speed” findings were mostly clarity findings. Profiling showed the nested solver dominates; caching ~8 transcendentals and preallocating buffers were measured as washes. They were kept for code health, with the speed claims explicitly retracted in the record.
A shared sign-conventions reference block now sits above E_from_Soil_to_Root_Collar, and a new test-leaf.r case (wet soil, zero light) locks in the sign relationships so the wart cannot silently return.

Where the detail lives

This is a high-level summary. The per-item analysis — line references, before/after rationale, validation digests, and the deliberate non-changes — lives in the original review document and the commit history in the plant repository:

https://github.com/traitecoevo/plant

The review was conducted against the develop commit badged above; consult the commit history around that point for the line-by-line changes and the A/B validation records referenced here.

Optimising the FF16 hot paths

Thu, 18 Jun 2026 00:00:00 GMT

plant @develop f8dbc4c

This post summarises a profiling-driven optimisation pass over the FF16 solver (PR #471). The work was guided by Rprof() plus native /usr/bin/sample profiles of the run_plant_benchmarks() FF16 scenarios, and the governing constraint was that every accepted change be bit-identical against HEAD (or its trajectory shift quantified) before being kept. The headline result: roughly 2.7-3.5x on the FF16 benchmarks, with the science provably unchanged.

Headline numbers

Measured as one-iteration bench::mark() timings (FF16 scenario):

Stage	`scm`	`build_schedule`
Original baseline (`4b5c43d1`)	242 ms	656 ms
After the optimisation pass	~85 ms	~186 ms
Speedup	~2.7x	~3.5x

The gains accumulated across ~15 individual changes, each profiled and verified in turn rather than landed as one big rewrite.

Where the time was going

Native profiling pointed at a handful of hot regions, all on the per-node, per-step physiology path:

Crown assimilation quadrature — std::function callable overhead and redundant canopy-shape work dominated the integrand.
Spline / interpolator lookups — repeated, bounds-checked evaluations and per-point binary searches during assimilation.
Competition / environment recomputation — inverse-height competition ratios recomputed every call.
Gradient calculation — physiology copied and recomputed via a per-call Internals allocation.
String/map lookups — state and aux variables addressed by name on the hot path.

How it was done

Each row below is an independently profiled, bit-identical change. Where machine drift between sessions made cumulative ratios unreliable, the honest figure was re-measured as a same-session A/B/A comparison (documented in the tracking note).

Target	Change	Effect
Assimilation quadrature	Direct-lambda integrand (drop `std::function`); eta-specialised canopy shape (issue #465); ratio-based `q()` path	Largest single contributor — ~1.4-1.5x from the canopy-shape specialisation alone
Spline lookups	Inline interpolator accessors + unchecked eval; hoist `spline.max()` out of the integrand; O(1)-guess + nudge lookup replacing per-point binary search	~3.5x on `build_schedule` traces back largely here
Competition	Cache the inverse-height competition ratio; dependent-aux height-inverse cache	~1.7x cumulative on competition-bound paths
Gradients	Reuse a thread-local scratch `Individual` (no per-call `Internals` alloc)	Removed per-gradient heap churn
State/rate addressing	Direct hot-path state/aux indices instead of string/map lookups	~1.9x on the indexed paths
Allocation derivatives	Dedup `pow()` and reuse `area_sapwood`/`mass_sapwood` from `net_mass_production_dt`	Bit-identical, timing-neutral hygiene; kept for clarity
FF16 strategy	Inline competition helpers + `area_leaf` into `ff16_strategy.h`; inline `util::is_finite` into a header	~1.2-1.3x from removing call overhead on the tightest loops

Notes on measurement discipline

A recurring theme — and the reason the tracking note is so long — is that these runs are short (hundreds of ms) with a ~10% run-to-run noise floor, and the macOS /usr/bin/sample profiler perturbs Rprof totals when it attaches successfully. Several apparent “regressions” were measurement artefacts:

A Sampler-Effect Audit isolated the inflation caused by concurrent sampling; the sample-off figures are the ones to trust for small changes.
Cross-session comparisons were re-grounded with same-session A/B/A re-measurements before any speedup was claimed.
An LTO experiment (issue #470) showed no measurable gain and was declined rather than kept speculatively.

Note

Bit-identical optimisations that turned out to be timing-neutral were deliberately kept where they improved clarity (e.g. the pow() dedup), and declined where they added complexity for no measured benefit (LTO). “Faster” was never allowed to mean “different answer” — the FF16 reference baselines gate the whole pass.

A soil-water bucket model from AWRA-L

Mon, 15 Jun 2026 00:00:00 GMT

plant @develop 81cfeab

Note

The observational dataset this post is built around (precipitation and soil moisture from Edaphic at the Corrie Downs and Delta sites) is not bundled with this repository. Every chunk that reads, prepares, or validates against that data is set #| eval: false. The self-contained model definitions (rate functions, ODE setup, parameter helpers) are kept verbatim and run.

Load packages

library(tidyverse)
library(ggplot2)
library(patchwork)

Load observational data

First lets open up some observational data from Edaphic at the Corrie Downs site. It has precipitation and soil moisture observations.

Not run: reads the Corrie Downs observational CSV, which isn’t bundled with this repo.

read_csv("~/Documents/GitHub/plant/vignettes/models/export-edap61.Falster.NSW.Corrie Downs weather-6.csv") %>%
  filter(Id != "Units") %>%
  setNames(as.character(.[1,])) %>%
  slice(-1) -> soil_moist_obs

# Extract layer names to identify depths. Layer 1 is 10cm deep, 2 20cm, etc.
str_extract_all(names(soil_moist_obs)[-1], "\\d+") %>%
  map(~.x[3]) %>%
  unlist() -> layernames

names(soil_moist_obs)[-1] <- layernames

# Turn timedate stamps into R readable dates
soil_moist_obs %>%
  rename(Prec_mm_per_15min = 17) %>%
  pivot_longer(cols = -c(Prec_mm_per_15min,Timestamp), names_to = "depth", values_to = "Soil_moist") %>%
  mutate(dom = lubridate::day(Timestamp)) %>%
  mutate(mod = lubridate::minute(Timestamp)) %>%
  mutate(hod = lubridate::hour(Timestamp)) %>%
  mutate(week = lubridate::week(Timestamp)) %>%
  mutate(moy = lubridate::month(Timestamp)) %>%
  # Precipitation is in units of mm/15mins
  mutate(Prec_mm_per_15min = as.numeric(Prec_mm_per_15min)) %>%
  # Convert those rates into units of mm/day (for each 15 step) %>%
  mutate(Prec_mm_per_day = as.numeric(Prec_mm_per_15min*96)) %>%
  # Calculating total rainfall per week
  group_by(week, depth) %>%
  mutate(Prec_mm_per_week = sum(Prec_mm_per_15min)) %>%
  # mutate(Prec_mm_per_week = Prec_mm_per_15min*96*7) %>%
  # m3 water per m3 soil - measured using electrical field
  mutate(Soil_moist = as.numeric(Soil_moist)) -> soil_moist_obs

Not run: depends on the observational soil_moist_obs loaded above.

soil_moist_obs %>%
  ggplot(aes(x = lubridate::as_date(Timestamp), y = as.numeric(Soil_moist))) +
  geom_line(aes(colour = depth, group = depth)) -> a

soil_moist_obs %>%
  ggplot(aes(x = lubridate::as_date(Timestamp), y = as.numeric(Prec_mm_per_day))) +
  geom_line() -> b

a/b

Prepare observational data

Not run: data prep depends on the observational soil_moist_obs.

# Make date-delisted timestep
soil_moist_obs%>%
  group_by(Timestamp) %>%
  nest() %>%
  ungroup() %>%
  mutate(timestep = seq(1:n()) - 1) %>%
  mutate(timestep = timestep / 96) %>%
  filter(timestep > 100) %>%
  unnest(data) -> soil_moist_obs


# Creating precipitation data table using the total rainfall per week data
soil_moist_obs  %>%
  group_by(week) %>%
  slice(1) %>%
  arrange(timestep) -> Prec_obs

# Spline function using the precipitation data
Prec_spline <- splinefun(x = Prec_obs$timestep, y = Prec_obs$Prec_mm_per_week)

Number of soil layers

Not run: derives the layer count from the observational data.

soil_layers = length(unique(soil_moist_obs$depth))

Frost, A. J., and Shokri, A., (2021) The Australian Landscape Water Balance model (AWRA-L v7). Technical Description of the Australian Water Resources Assessment Landscape model version 7. Bureau of Meteorology Technical Report

Melton et al., (2017) Tiling soil textures for terrestrial ecosystem modelling via clustering analysis: a case study with CLASS-CTEM (version 2.1) depending on

Cosby et al. (1984) A Statistical Exploration of the Relationships of Soil Moisture Characteristics to the Physical Properties of Soils

Functions

#### Parameters functions

# Saturated hydraulic conductivity (mm day^-1) depends on sand content

K_sat_ <- function(sand_con){
  # Melton et al., (2017)
  7.0556e-6*exp(0.0352*sand_con-2.035) * 1000 * 60*60*24
}

# Slope (%)

Beta_ <- function(avg_Slope){
  avg_Slope/(2*pi)*100
}

# Unscaled reference precipitation controls infiltration-excess runoff (mm day^-1)

P_refmap_ <- function(sand_con, Beta){
  20*(2 + log(K_sat_(sand_con)/Beta))
}


# Soil saturation capacity (mm)

# Parameters from Cosby et al. (1984)
Sz_sat_ <- function(sand_con, dz){
  dz*((50.5 -0.142*sand_con)/100)
}

#### Rates functions

# Infiltration-excess runoff (mm day^-1)

Qh_ <- function(P, Qh_switch){
  Qh_switch * P_refmap*tanh(P/P_refmap)
}

# Drainage rate (mm day ^ -1)

Dz_ <- function(Sz, i){
  K_sat*(Sz/Sz_sat[i])^2
}

Soil water model

rates_psi_FS_2021 <- function(t, Sz, params) {
  with(as.list(c(Sz, params)), {
    # Sz values are in mm
    dSz_dt <- rep(NA_real_, nlayers)
    Dz <- rep(NA_real_, nlayers)
    Qh <- rep(NA_real_)
    # Calculate fluxes at boundaries
    # top boundary layer - depends on soil water content, rain, soil water evaporation
    P <- pmax(P_func_(t), 0) # pmax(x, 0) forces all negative values to zero
    Qh <- Qh_(P, Qh_switch)
    I = P - Qh
    Dz[1] <- Dz_(Sz[1], 1)
    dSz_dt[1] = I - Dz[1]
    # Boundary below each node, except the last one
    # Eq. 3 + 11, Ireson et al. (2023)
    for (i in seq_len(nlayers-1)) {
      Dz[i + 1] <- Dz_(Sz[i + 1], i + 1)
      dSz_dt[i + 1] = -Dz[i + 1] + Dz[i]
    }

    return(list(dSz_dt = dSz_dt, Qh = Qh, P = P, I = I))
  })
}

Ode solver

solve <- function(times, rates, state, method = "rk4", output = "theta") {

  deSolve::ode(
    y = state,
    times = times,
    func = rates,
    parms = params,
    method = method) %>%
  as_tibble() %>%
  pivot_longer(-c(time, Qh, P, I), names_to = "depth", values_to = output)
}

Parameters

Not run: parameter block depends on soil_layers, derived from the observational data.

  # Soil info
  nlayers = soil_layers
  # Soil depth (mm)s
  soil_depth = 1.5e3
  # Different depths through sequence (mm)
  z = seq(soil_depth/nlayers, soil_depth, length.out= nlayers)
  # Distances between depths starting from 0 (mm)
  dz = diff(c(0,z))
  clay_con = 34 # Clay (%)
  sand_con = 10 # Sand (%)
  # Saturated conducitivity (mm day ^-1)
  K_sat = K_sat_(sand_con)

  # One value per soil layer
  Sz_sat = Sz_sat_(sand_con, dz)

  # Slope parameters (i.e. relating to the effect of slope on drainage)
  P_refscale = 2.637 # unitless
  avg_Slope = 10^-3 # radians
  Beta = Beta_(avg_Slope) # Slope (percent)
  P_refmap = P_refmap_(sand_con, Beta) # Unscaled reference precipitation (mm day^-1)

  # Set to 0 to disable runoff
  Qh_switch = 0

  P_ref = P_refmap*P_refscale # Scaled reference precipitation

  # Change which function is used to represent precipitation in the model

  # P_func_ <- function(t) {Prec_spline(t)} # Use spline function to represent precipitation
  # P_func_ <- function(t) {30*sin(t)+30} # Change precipitation function to a sine wave. First number is amplitude, second is the y-axis midpoint.
  P_func_ <- function(t) {t = 1} # Testing constant precipitation

params <- list(
  # Soil info
  nlayers = soil_layers,
  soil_depth = soil_depth,
  z = z,
  clay_con = clay_con, # Clay (%)
  sand_con = sand_con, # Sand (%)
  K_sat = K_sat,
  Sz_sat = Sz_sat,

  # Slope parameters
  P_refscale = P_refscale, # unitless
  avg_Slope = avg_Slope, # radians
  Beta = Beta, # Slope (percent)
  P_refmap = P_refmap, # Unscaled reference precipitation
  P_ref = P_ref, # Scaled reference precipitation
  Qh_switch = Qh_switch, # Runoff switch
  P_func_ = P_func_
)

Not run: timesteps are spanned from the observational record.

# generates timesteps per 15 minutes
timesteps <- seq(min(soil_moist_obs$timestep), max(soil_moist_obs$timestep), by = 1/96)

# generates timesteps per 10 days
timesteps <- seq(min(soil_moist_obs$timestep), max(soil_moist_obs$timestep), by = 10)

Not run: initial state and the deSolve run depend on the observational data.

# Setting initial state of all soil layers
init_state <- soil_moist_obs %>%
  slice(1:nlayers) %>%
  arrange(as.numeric(depth)) %>%
  pull(Soil_moist) %>%
  as.numeric()

Sz_solve_ode23 <- solve(times = timesteps, rates=rates_psi_FS_2021, state=init_state, method="ode23", output = c("Sz"))

Not run: validation plot compares the solve against the observed series.

soil_moist_obs %>%
  ungroup() %>%
  mutate(depth = as.numeric(depth)) %>%
  mutate(timestep = as.numeric(timestep) %>% round(digits = 4)) %>% # standardising decimal places for left join
  select(Soil_moist, Timestamp, depth, timestep) -> soil_moist_obs_rearranged

# Sz_solve %>%
#   mutate(timestep = as.numeric(time) %>% round(digits = 4)) %>%
#   mutate(depth = as.numeric(depth)) -> Sz_solve

ggplot()+
  geom_line(data = soil_moist_obs_rearranged, aes(y = Soil_moist, x = timestep), col = "black") +
  geom_line(data = Sz_solve_ode23, aes(y = Sz, x = time), col = "red", linetype = 2) +
  ylim(0, 50) +
  # geom_line(data = Sz_solve_lsoda, aes(y = Sz, x = time), col = "blue", linetype = 2) +
  facet_wrap(~as.numeric(depth)) -> a

Sz_solve_ode23 %>%
  # left_join(soil_moist_obs_rearranged) %>%
  ggplot(aes(x = time)) +
  # ylim(0, 100) +
  geom_line(aes(y = as.numeric(P))) -> b


Sz_solve_ode23 %>%
  # left_join(soil_moist_obs_rearranged) %>%
  ggplot(aes(x = time)) +
  # ylim(0, 100) +
  geom_line(aes(y = as.numeric(Qh))) -> c


Sz_solve_ode23 %>%
  # left_join(soil_moist_obs_rearranged) %>%
  ggplot(aes(x = time)) +
  # ylim(0, 100) +
  geom_line(aes(y = as.numeric(I))) -> d


a/(b+c+d)

a+b

cpp implementation

Not run: loads plant from a hardcoded local source tree.

devtools::load_all("~/Documents/GitHub/plant/")

Not run: patch lifetime is derived from the observational time span.

p0 <- scm_base_parameters("TF24")
p0$max_patch_lifetime <- (max(soil_moist_obs$timestep) - min(soil_moist_obs$timestep))/365
p1 <- expand_parameters(trait_matrix(0.0825, "lma"), p0)

Not run: environment is initialised from observed soil moisture and rainfall.

n_depths = 15
env <- Environment("TF24")
env$set_soil_number_of_depths(n_depths)
env$K_sat <- K_sat/1000*365
env$soil_moist_sat <- Sz_sat[1]/100
env$b_infil <- 0
inits <- soil_moist_obs %>% group_by(timestep) %>% nest() %>% ungroup() %>% slice(1)  %>% unnest(data) %>% arrange(as.numeric(depth)) %>% pull(Soil_moist)
env$set_soil_water_state(c(rep(inits/100)))
env$extrinsic_drivers_set_constant("rainfall", 0.365)

soil_moist_obs %>%
  group_by(timestep, Prec_mm_per_15min) %>%
  nest() -> soil_moist_obs_nested


# env$extrinsic_drivers_set_variable(driver_name = "rainfall", x = (soil_moist_obs_nested$timestep - min(soil_moist_obs$timestep))/365, y = soil_moist_obs_nested$Prec_mm_per_15min/1000*(4*24*365))
#
# env$extrinsic_drivers_evaluate_range(driver_name = "rainfall", x = seq(0,0.2,length.out = 100))

Not run: runs the SCM against the observation-derived environment above.

out <- run_scm(p1, env, collect = TRUE)

out$env$soil_moist %>%
  mutate(soil_depth = out$env$soil_depth$soil_depth) -> Sz_solve_cpp

Sz_solve_cpp %>%
  mutate(soil_depth = soil_depth*10) -> Sz_solve_cpp

Sz_solve_cpp %>%
  mutate(time = time*365 + min(soil_moist_obs$timestep)) -> Sz_solve_cpp


Sz_solve_cpp %>%
  mutate(depth = as.numeric(soil_depth)) -> Sz_solve_cpp

Not run: compares the C++ solve against the observed series.

ggplot()+
  geom_line(data = soil_moist_obs_rearranged, aes(y = Soil_moist, x = timestep), col = "black") +
  geom_line(data = Sz_solve_cpp, aes(y = soil_moist*100, x = time), col = "red", linetype = 2) +
  ylim(0, 50) +
  # geom_line(data = Sz_solve_lsoda, aes(y = Sz, x = time), col = "blue", linetype = 2) +
  facet_wrap(~depth) -> a

soiltype <- tibble(soil = c("sand","loamsand","sandyloam","loam",
                "siltyloam","sandyclayloam","clayloam",                "siltyclayloam","sandyclay","siltyclay",
                "clay","fullclay"),
       sand = c(92,82,58,43,17,58,32,10,52,6,22,0),
       clay = c(3,6,10,18,13,27,34,34,42,47,58,100))

rmse <- c()
bias <- c()

Not run: sweeps soil textures, refitting against the observational data and computing RMSE/bias per type.

for(i in 1:nrow(soiltype)){

    # Soil info
  nlayers = soil_layers
  # Soil depth (mm)s
  soil_depth = 1.5e3
  # Different depths through sequence (mm)
  z = seq(soil_depth/nlayers, soil_depth, length.out= nlayers)
  # Distances between depths starting from 0 (mm)
  dz = diff(c(0,z))
  clay_con = soiltype$clay[i] # Clay (%)
  sand_con = soiltype$sand[i] # Sand (%)
  # Saturated conducitivity (mm day ^-1)
  K_sat = K_sat_(sand_con)

  # One value per soil layer
  Sz_sat = Sz_sat_(sand_con, dz)

  # Slope parameters (i.e. relating to the effect of slope on drainage)
  P_refscale = 2.637 # unitless
  avg_Slope = 10^-5 # radians
  Beta = Beta_(avg_Slope) # Slope (percent)
  P_refmap = P_refmap_(clay_con, Beta) # Unscaled reference precipitation
  P_ref = P_refmap*P_refscale # Scaled reference precipitation

params <- list(
  # Soil info
  nlayers = soil_layers,
  soil_depth = soil_depth,
  z = z,
  clay_con = clay_con, # Clay (%)
  sand_con = sand_con, # Sand (%)
  K_sat = K_sat,
  Sz_sat = Sz_sat,

  # Slope parameters
  P_refscale = P_refscale, # unitless
  avg_Slope = avg_Slope, # radians
  Beta = Beta, # Slope (percent)
  P_refmap = P_refmap, # Unscaled reference precipitation
  P_ref = P_ref # Scaled reference precipitation
)


state <- soil_moist_obs %>%
  slice(1:nlayers) %>%
  arrange(as.numeric(depth)) %>%
  pull(Soil_moist) %>%
  as.numeric()


Sz_solve <- solve(times = timesteps, rates=rates_psi_FS_2021, state=state, method="ode45", output = "Sz")

soil_moist_obs %>%
  ungroup() %>%
  mutate(depth = as.numeric(depth)) %>%
  select(Soil_moist, Timestamp, depth, timestep) -> soil_moist_obs_rearranged


Sz_solve %>%
  mutate(timestep = as.numeric(time)) %>%
  mutate(depth = as.numeric(depth)) %>%
  left_join(soil_moist_obs_rearranged) %>%
  select(Sz, Soil_moist,timestep) -> res

rmse[i] <- Metrics::rmse(res$Sz, res$Soil_moist)
bias[i] <- Metrics::bias(res$Sz, res$Soil_moist)

Sz_solve %>%
  rename(timestep = time) %>%
  mutate(timestep = as.numeric(timestep)) %>%
  mutate(depth = as.numeric(depth)) %>%
  # mutate(date = soil_moist_obs_rearranged$date) %>%
  left_join(soil_moist_obs_rearranged) %>%
  ggplot(aes(x = timestep)) +
  geom_line(aes(y = Sz)) +
  geom_line(aes(y = Soil_moist), col = "red") +
  facet_wrap(~as.numeric(depth)) -> p

print(p)

}

rmse
bias

Minimise rmse

Not run: refits the best-RMSE soil type against the observational data.

i = 1


## Parameters

  # Soil info
  nlayers = soil_layers
  soil_depth = 1.5e3
  z = seq(soil_depth/nlayers, soil_depth, length.out= nlayers)
  clay_con = soiltype[i,]$clay # Clay (%)
  sand_con = soiltype[i,]$sand # Sand (%)
  K_sat = K_sat_(clay_con, Kzsatscale_(z))
  Sz_sat = Sz_sat_(clay_con, sand_con, z)

  # Slope parameters
  P_refscale = 2.637 # unitless
  avg_Slope = 10^-5 # radians
  Beta = Beta_(avg_Slope) # Slope (percent)
  P_refmap = P_refmap_(clay_con, Beta) # Unscaled reference precipitation
  P_ref = P_refmap*P_refscale # Scaled reference precipitation

  S_awc = S_awc_(58,22)

  # Rain
  P = as.numeric(Prec_obs$Prec_mm_per_day)

params <- list(
  # Soil info
  nlayers = soil_layers,
  soil_depth = soil_depth,
  z = z,
  clay_con = clay_con, # Clay (%)
  sand_con = sand_con, # Sand (%)
  K_sat = K_sat,
  Sz_sat = Sz_sat,

  # Slope parameters
  P_refscale = P_refscale, # unitless
  avg_Slope = avg_Slope, # radians
  Beta = Beta, # Slope (percent)
  P_refmap = P_refmap, # Unscaled reference precipitation
  P_ref = P_ref, # Scaled reference precipitation

  S_awc = S_awc,

  # Rain
  P = P
)


state <- soil_moist_obs %>%
  slice(1:nlayers) %>%
  arrange(depth) %>%
  pull(Soil_moist)


Sz_solve <- solve(times = timesteps, rates=rates_psi_FS_2021, state=state, method="lsoda", output = "Sz")

soil_moist_obs %>%
  ungroup() %>%
  mutate(depth = as.numeric(depth)) %>%
  select(Soil_moist, Timestamp, depth, timestep) -> soil_moist_obs_rearranged

Sz_solve %>%
  mutate(timestep = as.numeric(time)) %>%
  mutate(depth = as.numeric(depth)) %>%
  left_join(soil_moist_obs_rearranged) %>%
  ggplot(aes(x = time)) +
  geom_line(aes(y = as.numeric(Sz))) +
  geom_line(aes(y = as.numeric(Soil_moist)), col = "red") +
  facet_wrap(~as.numeric(depth))

Minimise bias

Not run: refits the best-bias soil type against the observational data.

i = 4

## Parameters

  # Soil info
  nlayers = soil_layers
  soil_depth = 1.5e3
  z = seq(soil_depth/nlayers, soil_depth, length.out= nlayers)
  clay_con = soiltype[i,]$clay # Clay (%)
  sand_con = soiltype[i,]$sand # Sand (%)
  K_sat = K_sat_(clay_con, Kzsatscale_(z))
  Sz_sat = Sz_sat_(clay_con, sand_con, z)

  # Slope parameters
  P_refscale = 2.637 # unitless
  avg_Slope = 10^-5 # radians
  Beta = Beta_(avg_Slope) # Slope (percent)
  P_refmap = P_refmap_(clay_con, Beta) # Unscaled reference precipitation
  P_ref = P_refmap*P_refscale # Scaled reference precipitation

  S_awc = S_awc_(58,22)

  # Rain
  P = as.numeric(Prec_obs$Prec_mm_per_day)

params <- list(
  # Soil info
  nlayers = soil_layers,
  soil_depth = soil_depth,
  z = z,
  clay_con = clay_con, # Clay (%)
  sand_con = sand_con, # Sand (%)
  K_sat = K_sat,
  Sz_sat = Sz_sat,

  # Slope parameters
  P_refscale = P_refscale, # unitless
  avg_Slope = avg_Slope, # radians
  Beta = Beta, # Slope (percent)
  P_refmap = P_refmap, # Unscaled reference precipitation
  P_ref = P_ref, # Scaled reference precipitation

  S_awc = S_awc,

  # Rain
  P = P
)


state <- soil_moist_obs %>%
  slice(1:nlayers) %>%
  arrange(depth) %>%
  pull(Soil_moist)


Sz_solve <- solve(times = timesteps, rates=rates_psi_FS_2021, state=state, method="lsoda", output = "Sz")

soil_moist_obs %>%
  ungroup() %>%
  mutate(depth = as.numeric(depth)) %>%
  select(Soil_moist, Timestamp, depth, timestep) -> soil_moist_obs_rearranged

Sz_solve %>%
  mutate(timestep = as.numeric(time)) %>%
  mutate(depth = as.numeric(depth)) %>%
  left_join(soil_moist_obs_rearranged) %>%
  ggplot(aes(x = time)) +
  geom_line(aes(y = as.numeric(Sz))) +
  geom_line(aes(y = as.numeric(Soil_moist)), col = "red") +
  facet_wrap(~as.numeric(depth))

Delta bare soil example

Not run: reads the Delta site observational CSV, which isn’t bundled with this repo.

read_csv("~/Documents/export-edap61.Falster.NSW.Delta weather (extra soil)-2.csv") %>%
  filter(Id != "Units") %>%
  setNames(as.character(.[1,])) %>%
  slice(-1) -> soil_moist_obs

str_extract_all(names(soil_moist_obs)[-1], "\\d+") %>%
  map(~.x[2]) %>%
  unlist() -> layernames

names(soil_moist_obs)[-1] <- layernames

soil_moist_obs %>%
  rename(Prec_mm_per_15min = 5) %>%
  pivot_longer(cols = -c(Prec_mm_per_15min,Timestamp), names_to = "depth", values_to = "Soil_moist") %>%
  mutate(date = lubridate::as_date(Timestamp)) %>%
  filter(date > lubridate::as_date("2025-09-14")) %>%
  mutate(dom = lubridate::day(Timestamp)) %>%
  mutate(mod = lubridate::minute(Timestamp)) %>%
  mutate(hod = lubridate::hour(Timestamp)) %>%
  mutate(moy = lubridate::month(Timestamp)) %>%
  mutate(Prec_mm_per_15min = as.numeric(Prec_mm_per_15min)) %>%
  mutate(Prec_mm_per_day = Prec_mm_per_15min*96) %>%
  mutate(Soil_moist = as.numeric(Soil_moist)) -> soil_moist_obs

Not run: depends on the Delta observational data.

soil_moist_obs %>%
  ggplot(aes(x = lubridate::as_date(Timestamp), y = as.numeric(Soil_moist))) +
  geom_line(aes(colour = depth, group = depth))

Not run: depends on the Delta observational data.

soil_moist_obs %>%
  ggplot(aes(x = lubridate::as_date(Timestamp), y = as.numeric(Prec_mm_per_15min))) +
  geom_line(aes(colour = depth, group = depth))

Not run: data prep depends on the Delta observational data.

soil_moist_obs%>%
  group_by(Timestamp) %>%
  nest() %>%
  arrange(Timestamp) %>%
  ungroup() %>%
  mutate(timestep = seq(1:n()) - 1) %>%
  mutate(timestep = timestep / 96) %>%
  unnest(data) -> soil_moist_obs

soil_moist_obs  %>%
  group_by(Timestamp) %>%
  slice(1) %>%
  arrange(Timestamp)-> Prec_obs

Not run: derives the layer count from the Delta observational data.

soil_layers = length(unique(soil_moist_obs$depth))

rates_psi_FS_2021 <- function(t, Sz, params) {
  with(as.list(c(Sz, params)), {
    dSz_dt <- rep(NA_real_, nlayers)
    Dz_ <- rep(NA_real_, nlayers)

    # Calculate fluxes at boundaries
    # top boundary layer - depends on soil water content and rain
    I = P[t+1] - Qh_(P[t+1])
    Dz_[1] <- Dz(Sz[1], 1)
    dSz_dt[1] = I - Dz_[1] - E(Sz[1])
    # Boundary below each node, except the last one
    # Eq. 3 + 11, Ireson et al. (2023)
    for (i in seq_len(nlayers-1)) {
      Dz_[i + 1] <- Dz(Sz[i + 1], i + 1)
      dSz_dt[i + 1] = -Dz_[i + 1] + Dz_[i]
    }

    return(list(dSz_dt))
  })
}

Not run: solve depends on the observation-derived timesteps and state.

Sz_solve <- solve(times = timesteps, rates=rates_psi_FS_2021, state=state, method="lsoda", output = "Sz")

Hydraulics inner-loop benchmark

Wed, 10 Jun 2026 00:00:00 GMT

plant @develop a1b2c3d

This post is built against an unreleased commit on develop, so the badge pins to a SHA rather than a version. The simulation below is slow, so it’s pinned to its own renv snapshot as well — a later project-wide package upgrade can’t change this result even on a forced re-run.

Per-post environment

This directory carries its own lockfile, captured once when the post was written:

# run from this post's directory, once:
renv::snapshot(lockfile = "renv.lock.dev", prompt = FALSE)

plant_session_info() (footer) reports renv.lock.dev when present, so the page records exactly which environment produced the figures. To reproduce: check out plant at the SHA above, renv::restore(lockfile = "renv.lock.dev"), delete this post’s _freeze/ entry, re-render.

The sweep

library(plant)
library(bench)

lai_grid <- seq(1, 8, by = 0.5)

results <- lapply(lai_grid, function(L) {
  bench::mark(
    baseline  = run_inner_ff16(lai = L),
    hydraulic = run_inner_hydraulics(lai = L),
    iterations = 20, check = FALSE
  )
})

# ... ggplot of median time by method across lai_grid ...

Note

Numbers here are frozen to commit a1b2c3d. When this work lands on master, supersede this post with a release-pinned version rather than editing it — keeping the develop snapshot as the historical record.

When the Richards equation fights back

Tue, 29 Jul 2025 00:00:00 GMT

We’ve recently been trying to expand the TF24 strategy to handle soil water, but our initial attempt encountered serious instability after we implemented the Richards equation. The symptom was unmissable: with anything but an absurdly small time step the integrator produced nonsense within a few steps — soil moisture leaping above saturation, going negative, then collapsing to NaN. The same pathology showed up whether the equation was implemented in C++ or in R, which is the first clue that the problem is mathematical rather than a coding slip.

This post works through a minimal R reproduction of that instability, shows the contrast between an explicit and an implicit solver, and ends with the diagnosis: the discretised Richards equation is stiff, and no amount of careful coding will rescue an explicit Runge–Kutta scheme from it. The full back-and-forth — including the -based form, a single-bucket fallback, and a delay-equation experiment — lives in traitecoevo/plant discussion #444; here we keep just enough to stand on its own.

Note

This is a standalone numerical experiment. It prototypes the soil-water dynamics directly with deSolve and does not use the plant package API, so it isn’t pinned to a plant version — the point is the solver behaviour, which is independent of the model it will eventually live in.

library(dplyr)
library(tidyr)
library(ggplot2)
library(deSolve)

The model

We track volumetric soil water content on a vertical grid of nodes. Each node exchanges water with its neighbours by Darcy flux, driven by gradients in the matric potential , plus gravity. This is the mixed form of the Richards equation, following Ireson et al. (2023):

The constitutive relations — hydraulic conductivity and matric potential — are the usual power laws:

pow <- function(x, y) x^y

soil_K_from_soil_theta <- function(theta, K_sat = 440.628,
                                   soil_moist_sat = 0.453, n_psi = 4.8) {
  K_sat * pow(theta / soil_moist_sat, 2 * n_psi + 3)
}

psi_from_soil_moist <- function(soil_moist, soil_moist_sat = 0.453,
                                a_psi = 8.7, n_psi = 4.8) {
  a_psi * pow(soil_moist / soil_moist_sat, -n_psi)
}

params <- list(
  soil_moist_sat = 0.453,   # saturated water content (m^3/m^3)
  K_sat          = 440.628, # saturated conductivity (units below)
  n_psi          = 4.8,     # pore-size distribution exponent
  a_psi          = 8.7,     # air-entry scaling
  b_infil        = 8.0,     # infiltration shape parameter
  rain           = 1,       # rainfall forcing
  n              = 10       # number of soil nodes
)

The right-hand side assembles the inter-node fluxes — an infiltration flux at the surface that shuts off as the top layer saturates, Darcy fluxes between interior nodes, and a free-drainage lower boundary ( at the bottom) — then differences them to get at each node:

rates <- function(t, theta, params) {
  with(as.list(c(theta, params)), {

    psi <- psi_from_soil_moist(theta, soil_moist_sat = soil_moist_sat)
    K   <- soil_K_from_soil_theta(theta, soil_moist_sat = soil_moist_sat)

    q  <- rep(NA_real_, n + 1)
    dz <- rep(2 / n, n)
    dtheta_dt <- rep(NA_real_, n)

    # top boundary: infiltration, shutting off as the top layer fills
    q[1] <- rain * max(0.0, 1 - pow(theta[1] / soil_moist_sat, b_infil))

    # interior boundaries: Darcy flux (Eq. 3 + 11, Ireson et al. 2023)
    for (i in seq_len(n - 1)) {
      dpsi_dz  <- (psi[i + 1] - psi[i]) / dz[i]
      q[i + 1] <- 0.5 * (K[i] + K[i + 1]) * (dpsi_dz - 1)
    }

    # lower boundary: free drainage (Eq. 13, Ireson et al. 2023)
    q[n + 1] <- K[n]

    # divergence of flux gives the rate of change at each node (Eq. 10)
    for (i in seq_len(n)) {
      dq_dz <- (q[i + 1] - q[i]) / dz[i]
      dtheta_dt[i] <- -dq_dz
    }

    list(dtheta_dt)
  })
}

A small wrapper integrates the system and returns a long-format tibble, and a helper plots at each depth over time:

solve_soil <- function(times, rates, state, method = "rk4", output = "theta") {
  ode(y = state, times = times, func = rates, parms = params, method = method) %>%
    as_tibble() %>%
    pivot_longer(-time, names_to = "depth", values_to = output) %>%
    mutate(depth = factor(as.integer(depth)))
}

plot_solution <- function(solution) {
  solution %>%
    ggplot(aes(x = time, y = theta, colour = depth)) +
    geom_line() +
    labs(x = "time (yr)", y = expression(theta), colour = "node") +
    theme_minimal()
}

n <- 10
state <- rep(0.2533, n)

The instability

Now integrate with the classic explicit Runge–Kutta solver (rk4) at a time step of yr — about an hour, which sounds harmlessly small:

fail <- solve_soil(times = seq(0, 1e-3, by = 1e-4),
                   rates = rates, state = state, method = "rk4")
plot_solution(fail)

Figure 1: Explicit RK4 at Δt = 1e-4 yr. The solution explodes within two steps — moisture overshoots saturation, goes negative, then becomes NaN (gaps in the lines).

It detonates almost immediately. Printing the first few steps for the top nodes shows the runaway in numbers: a steady start, then values flung well past the physical range, then NaN:

fail %>%
  filter(depth %in% c(1, 2, 3)) %>%
  pivot_wider(names_from = depth, values_from = theta, names_prefix = "node ") %>%
  head(4)

# A tibble: 4 × 4
  time      `node 1`  `node 2`  `node 3`  
      
1 0e+00     0.2533000 0.2533000  0.2533000
2 1e-04     0.2531335 0.2544907  0.2527162
3 2e-04     0.1836168 0.5842660 -0.1377172
4 3e-04           NaN       NaN        NaN

This is not a bug in the right-hand side — the rates are continuous and correct. It’s the explicit integrator amplifying tiny errors faster than the dynamics damp them, the hallmark of a stiff system.

The reflex fix is to shrink the step. At yr (~5 minutes) RK4 does stay stable:

ok <- solve_soil(times = seq(0, 1e-2, by = 1e-5),
                 rates = rates, state = state, method = "rk4")
plot_solution(ok)

Figure 2: Explicit RK4 at Δt = 1e-5 yr stays stable — but this is only the first hundredth of a year, and already cost 1000 steps. A full year needs 100,000.

The infiltration front is smooth and physical — but look at the cost. That figure covers just of a year and already took 1000 steps. Integrating a single year would need 100,000 explicit steps, and a forest simulation runs for centuries. This is not a viable solver for the model.

The fix: an implicit solver

Stiffness is solved by implicit methods, which evaluate the right-hand side at the end of the step and so remain stable at large step sizes. deSolve’s lsoda switches automatically between stiff and non-stiff modes. Swapping it in — and taking a step of yr, ten thousand times larger than the one RK4 needed — integrates the whole year cleanly:

stable <- solve_soil(times = seq(0, 1, by = 0.1),
                     rates = rates, state = state, method = "lsoda")
plot_solution(stable)

Figure 3: Implicit LSODA at Δt = 0.1 yr integrates a full year in ~10 steps with no instability.

Same right-hand side, same parameters, same initial condition — the only change is the solver, and the instability is gone. That is the clean experimental proof that the problem was stiffness all along.

Why this happens

The Richards equation is a nonlinear, degenerate elliptic–parabolic PDE. As Farthing & Ogden (2017) put it, it is “degenerate” because its strongly nonlinear coefficients approach zero in parts of the solution domain. Here the conductivity spans many orders of magnitude across the profile: with that exponent is about , so a modest moisture gradient produces an enormous spread of local timescales between nodes. Fast nodes set the stability limit of an explicit step; slow nodes set how long you must integrate. The ratio between them is the stiffness, and it forces explicit methods into impractically tiny steps.

Takeaways for the soil-water work

The instability is intrinsic to the discretised Richards equation, not to our implementation — it reproduced identically in C++ and R.
Explicit Runge–Kutta is the wrong tool. The model needs an implicit / adaptive stiff solver (LSODA, or a BDF-type method) if we keep the full Richards profile.
If a stiff solver proves awkward to embed in the strategy’s inner loop, the discussion explores cheaper alternatives — a single- or two-layer bucket model, or a Kirchhoff-transform linearisation (Ross 2003) — that sidestep the stiffness rather than solving it.

The next step for TF24 soil water is to decide between embedding an implicit solver and adopting a reduced-order bucket model; this experiment is what ruled out the naive explicit route.

References

Farthing, M. W. & Ogden, F. L. (2017). Numerical solution of Richards’ equation: a review of advances and challenges. Soil Science Society of America Journal, 81(6), 1257–1269.
Ireson, A. M. et al. (2023). The finite volume method for solving the Richards equation. Hydrology and Earth System Sciences.
Ross, P. J. (2003). Modeling soil water and solute transport — fast, simplified numerical solutions. Agronomy Journal, 95(6), 1352–1361.
traitecoevo/plant discussion #444 — Problem modelling soil water with Richards Equation. ```

Prototyping a soil water-balance bucket model

Wed, 22 May 2024 00:00:00 GMT

Note

This is an exploratory experiment from 2021, kept for the record. It prototypes soil water dynamics directly with deSolve and does not use the plant package API — it is not maintained and may not reflect the current model.

Originally authored by Isaac Towers, 2021-05-19.

library(dplyr)
library(tidyr)
library(ggplot2)
library(purrr)
library(deSolve)

Here I will develop the prototype for the water bucket model for the plant model tracking the rate of change in

Variables

: soil volumetric water content

Parameters

: Rainfall : Infiltration rate (unitless) : Transpiration (water used by plants) : Soil surface evaporation : Drainage from soil profile : Soil depth (m)

: Unitless parameter determining the shape of water accumulation in the soil moisture bank Soil moisture capacity

Ok, lets first show that rain will eventually fill up the soil without any water outputs if we include a saturated water content

# Timestep
t <- seq(0,365, by = 1)

# Variables
theta_init <- c(theta=0.210)

# Model parameters
params <-
  expand_grid(theta_sat = 0.513,
            R  = 1000/365,
            b = c(1, 0.5, 2, 4, 8),
            z = 1000) %>%
        split(., .$b)

# Rates of change
theta_rates <- function(t, theta, params) {
  with(as.list(c(theta, params)), {

    dtheta_dt = (R*(1-(theta/theta_sat)^b))/z

    return(list(c(dtheta_dt)))
  })
}

logistic_solution <-
  map_dfr(
    params,
    ~ode(
    y = theta_init,
    times = t,
    func = theta_rates,
    parms = .x) %>%
  as.data.frame(), .id = "b")

logistic_solution %>%
  ggplot(aes(time, theta, col=b)) +
  geom_line()

Cool, let’s now include a drainage factor.

The soil moisture content in the top layer of soil is defined the soil moisture between 0m depth and the first monited depth point as follows:

where rainfall enters the soil and drains at rate: and represents the first monitored soil depth.

For all layers below the first, the soil moisture content is defined as follows:

where is the drainage of soil water from above.

Because we are still unsure about how water flux works with regards to the balance bewteen matric and gravitational potential, we will use a much more simplified version of water flux employed by Duursma and Medlyn (2012) where water is assumed to only travel downwards and is directly equivalent to the soil hydraulic conductivity ):

where:

and and (unitless) are empirical parameter which vary with soil type

# Timestep
t <- seq(0,365, by = 1)

# Variables
theta_init <- c(theta1=0.513, theta2=0, theta3=0)

# Model parameters for silty loam (Landsberg)
params <-
  expand_grid(theta_sat = 0.513,
    R  = 1/365,
    #convert to day
    ksat = c(12.2*24),
    nk = 11.9
    ) %>%
        split(., .$ksat)

# Rates of change
theta_rates <- function(t, theta, params) {
  with(as.list(c(theta, params)), {
    dtheta1_dt = R - (ksat * (theta1/theta_sat)^nk)/0.1
    dtheta2_dt = ((ksat * (theta1/theta_sat)^nk) - (ksat * (theta2/theta_sat)^nk))/0.5
    dtheta3_dt = ((ksat * (theta2/theta_sat)^nk))/0.5
    return(list(c(dtheta1_dt,dtheta2_dt,dtheta3_dt)))
  })
}

logistic_solution <-
  map_dfr(
    params,
    ~ode(
    y = theta_init,
    times = t,
    func = theta_rates,
    parms = .x) %>%
  as.data.frame(), .id = "ks")

logistic_solution %>%
 ggplot(aes(time)) +
  geom_line(aes(y = theta1, col="Top Layer")) +
  geom_line(aes(y = theta2, col="Middle Layer")) +
  geom_line(aes(y = theta3, col="Bottom Layer"))

An alternative which does allow for upwards flux is to calculate water flux based on diffusivity,D, :

where D is equal to:

In this example, is calculated as:

and the same for :

# Timestep
t <- seq(0,1000, by = 0.1)

# Variables
theta_init <- c(theta11=0, theta22=0, theta33=0, theta44=0)



# Model parameters for silty loam (Landsberg)
params <- list(
  c(
    R=3/365,
    dsat = 1.4,
    nd = 6.5,
    theta_sat = c(0.482),
    b=8,
    amp=0,
    I_constant=1,
    sine_height=1,
    frequency=180,
    ksat=292.8,
    nk=11.9
    ))


# Rates of change
theta_rates1 <- function(t, theta_init, params) {
  with(as.list(c(theta_init, params)), {
    dtheta1_dt=R-(-dsat*(theta11/theta_sat)^nd)*((theta22-theta11)/0.50)
    dtheta2_dt=(-dsat*(theta11/theta_sat)^nd)*((theta22-theta11)/0.50)-(-dsat*(theta22/theta_sat)^nd)*((theta33-theta22)/0.50)
    dtheta3_dt=(-dsat*(theta22/theta_sat)^nd)*((theta33-theta22)/0.50)-((ksat)*(theta33/theta_sat)^nk)
    dtheta4_dt=((ksat)*(theta33/theta_sat)^nk)

    return(list(c(dtheta1_dt,dtheta2_dt,dtheta3_dt,dtheta4_dt)))
  })
}

logistic_solution1 <-
  map_dfr(
    params,
    ~ode(
    y = theta_init,
    times = t,
    func = theta_rates1,
    parms = .x) %>%
  as.data.frame())

The same idea, now wired up as a general multi-layer model with configurable monitored depths, runoff and deep-drainage bookkeeping, and a seasonal rainfall signal.

#set time period and time step
t <- seq(0,1000, by = 1)

#how many soil depths should be monitored
n=3

#set depth of points, can be customised. N-1 in this case accounts for one customsied point, all others are the same
standard_depth = 0.5
z <- c(0.10, rep(standard_depth, n-1))

i=1

#set vector to collect gradients
dtheta_dt <- vector(length = n)

#set initial soil moisture content for each layer (boundary z[i] - z[i-1]) as well as the amount of water lost to deep drainage and runoff and the total amount of rainfall falling in period for sanity check, particulary important for when inclduing temporal variation
theta_init <- c(theta=rep(0, n), runoff = 0, deep_drainage=0, cumulative_rain=0)

#set parameter values
params <- list(
  c(
    R=3/365,
    dsat = 1.4,
    nd = 6.5,
    theta_sat = 0.482,
    b=8,
    ksat=292.8,
    nk=11.9,
    amp=1,
    sine_height=1,
    frequency=180,
    I_constant = 1
    ))
#soil moisture drainage model

theta_rates <- function(t, theta, params) {
  with(as.list(c(theta, params)), {

    I = (1-I_constant*(theta[i]/theta_sat)^b)
    S = amp*sin(t/frequency*pi)+sine_height

    for(i in 1:n){

    #top layer. Non-infiltrating rainfall is stored in runoff, but leaves the plant-accessible water budget forever.
      if(i == 1) {
    inflow = R*S*I
    runoff = (R*S)*(1-I)
    outflow = (-dsat*(theta[i]/theta_sat)^nd)*((theta[i+1]-theta[i])/z[i+1])

      }

    #middle layers
      if(!i %in% c(1, n)) {
     inflow = (-dsat*(theta[i-1]/theta_sat)^nd)*((theta[i]-theta[i-1])/z[i])
     outflow= (-dsat*(theta[i]/theta_sat)^nd)*((theta[i+1]-theta[i])/z[i+1])
      }

    # last layer - water that outflows from this layer is gone forever. Values are stored in deep_drainage.
      if(i == (n)) {
    inflow = (-dsat*(theta[i-1]/theta_sat)^nd)*((theta[i]-theta[i-1])/z[i])
    outflow = ((ksat)*(theta[i]/theta_sat)^nk)
    deep_drainage = ((ksat)*(theta[i]/theta_sat)^nk)
      }

    dtheta_dt[i] = inflow - outflow
    runoff = runoff
    deep_drainage = deep_drainage
    cumulative_rain = R*S
    }

    return(list(c(dtheta_dt, runoff, deep_drainage, cumulative_rain)))
  })
}

logistic_solution <-
  map_dfr(
    params,
    ~ode(
    y = theta_init,
    times = t,
    func = theta_rates,
    parms = .x) %>%
  as.data.frame())

logistic_solution %>%
  select(time, contains("theta")) %>%
  pivot_longer(., contains("theta")) %>%
  rename(Soil_depth = name) %>%
  ggplot(aes(time)) +
  geom_line(aes(y=value, col=Soil_depth))

A hard-coded ten-layer expansion of the same scheme, kept here as scratch working.

#ignore below for now


# Timestep
t <- seq(0,1000, by = 0.1)

# Variables
theta_init <- c(theta1=0, theta2=0, theta3=0, theta4=0, theta5=0, theta6=0, theta7=0, theta8=0, theta9=0, theta10=0, runoff = 0)


# Model parameters for silty loam (Landsberg)
params <- list(
  c(
    R=3/365,
    dsat = 1.4,
    nd = 6.5,
    theta_sat = c(0.482),
    b=8,
    I_constant=1,
    amp=0,
    sine_height=1,
    frequency=180,
    ksat=292.8,
    nk=11.9))

# Rates of change
theta_rates <- function(t, theta_init, params) {
  with(as.list(c(theta_init, params)), {
    I = (1-(theta1/theta_sat)^b)
    S = amp*sin(t/frequency*pi)+sine_height
    dtheta1_dt=R*S*I-(-dsat*(theta1/theta_sat)^nd)*((theta2-theta1)/0.25)
    dtheta2_dt=((-dsat*(theta1/theta_sat)^nd)*((theta2-theta1)/0.25)-(-dsat*(theta2/theta_sat)^nd)*((theta3-theta2)/0.25))
    dtheta3_dt=((-dsat*(theta2/theta_sat)^nd)*((theta3-theta2)/0.25)-(-dsat*(theta3/theta_sat)^nd)*((theta4-theta3)/0.25))
    dtheta4_dt=((-dsat*(theta3/theta_sat)^nd)*((theta4-theta3)/0.25)-(-dsat*(theta4/theta_sat)^nd)*((theta5-theta4)/0.25))
    dtheta5_dt=((-dsat*(theta4/theta_sat)^nd)*((theta5-theta4)/0.25)-(-dsat*(theta5/theta_sat)^nd)*((theta6-theta5)/0.25))
    dtheta6_dt=((-dsat*(theta5/theta_sat)^nd)*((theta6-theta5)/0.25)-(-dsat*(theta6/theta_sat)^nd)*((theta7-theta6)/0.25))
    dtheta7_dt=((-dsat*(theta6/theta_sat)^nd)*((theta7-theta6)/0.25)-(-dsat*(theta7/theta_sat)^nd)*((theta8-theta7)/0.25))
    dtheta8_dt=((-dsat*(theta7/theta_sat)^nd)*((theta8-theta7)/0.25)-(-dsat*(theta8/theta_sat)^nd)*((theta9-theta8)/0.25))
    dtheta9_dt=((-dsat*(theta8/theta_sat)^nd)*((theta9-theta8)/0.25))-((ksat)*(theta9/theta_sat)^nk)
    dtheta10_dt= ((ksat)*(theta9/theta_sat)^nk)
    # ((12.2*24)*(theta9/theta_sat)^11.9)
    runoff = R*S*(1-I)

    return(list(c(dtheta1_dt,dtheta2_dt, dtheta3_dt,dtheta4_dt,dtheta5_dt,dtheta6_dt,dtheta7_dt,dtheta8_dt,dtheta9_dt,dtheta10_dt
, runoff)))
  })
}

logistic_solution <-
  map_dfr(
    params,
    ~ode(
    y = theta_init,
    times = t,
    func = theta_rates,
    parms = .x) %>%
  as.data.frame())

logistic_solution %>%
 ggplot(aes(time)) +
  geom_line(aes(y = theta1, col="1st Layer")) +
  geom_line(aes(y = theta2, col="2nd Layer")) +
  geom_line(aes(y = theta3, col="3rd Layer"))+
  geom_line(aes(y = theta4, col="4th Layer"))+
  geom_line(aes(y = theta5, col="5th Layer"))+
  geom_line(aes(y = theta6, col="6th Layer"))+
  geom_line(aes(y = theta7, col="7th Layer"))+
  geom_line(aes(y = theta8, col="8th Layer"))+
  geom_line(aes(y = theta9, col="9th Layer"))

Now let’s add evaporation. We will use the Penman-Monteith equation to model evaporation as a water flux (rather than an energy flux):

Where E is the evaporation in m (i.e. ). This equation is dependent on the air temperature, which manifests its effect on evaporation through determining the vapour pressure deficit , and the derivative of the saturated vapour pressure curve at a given air temperature , the net radiation reaching the soil surface , and soil moisture which affects the soil conductance .

The equation for the saturated vapour pressure is dependent on air temperature only:

Thus,

To estimate the daily average vapour pressure deficit, the maximum and minimum air temperature can be used

and the daytime average vapour pressure deficit can be calculated by assuming a fraction of daytime hours :

Radiation reaching the soil surface (i.e. passing through the tree canopy) is assumed to be entirely absorbed. Thus, net radiation at the soil surface is defined as the radiation incident on the tree canopy minus the radiation absorbed the tree canopy

where is dependent on the leaf area index (LAI) of the canopy and the light extinction coefficient (k):

Conductance of water vapour through the soil moisture boundary layer is dependent on soil moisture, because resistance to evaporation increases as the soil becomes increasingly dry according the following equation. Using an equation proposed by Soares and Almeida (2001):

Once through the soil moisture boundary layer, water vapour must then travel through the atmospheric boundary layer according to the rate . For soil, a fixed value is currently assumed using value obtained from Soares and Almeida (2001) where

# Timestep
t <- seq(0,3650, by = 1)

# Variables
theta_init <- c(theta=0.513)

# Model parameters
params <-
  expand_grid(theta_sat = 0.513,
            R  = 1000/365,
            b = 8,
            gcmax=0.0025,
            gb=0.01,
            vpd=900,
            p = 1.204,
            cpa = 1004,
            y=66.1,
            s=145,
            air_temp=25,
            slope_sat_vap_curve = 4098*(0.6108*exp((17.27*air_temp)/(air_temp+237.3)))/(air_temp+237.3)^2 *1000,
            #radiation will be fed in from plant model based on its solar radiation submodel and plant lai
            rad = c(200,434),
            max_air_temp = 25,
            min_air_temp= 10,
            L = 2.45*10^6,
            z = 1500) %>%
            split(., .$rad)

# Rates of change
theta_rates <- function(t, theta, params) {
  with(as.list(c(theta, params)), {
    evap_numerator = slope_sat_vap_curve *rad + gb*p*cpa*vpd
    evap_denominator = slope_sat_vap_curve + y*(1+gb/(gcmax*(theta/theta_sat)))
    evap=evap_numerator/evap_denominator*(1/L)*12*60*60
    dtheta_dt = (R*(1-(theta/theta_sat)^b)- evap)/z

    return(list(c(dtheta_dt)))
  })
}

logistic_solution <-
  map_dfr(
    params,
    ~ode(
    y = theta_init,
    times = t,
    func = theta_rates,
    parms = .x) %>%
  as.data.frame(), .id = "rad")

logistic_solution %>%
  ggplot(aes(time, theta, col=rad)) +
  geom_line()

# Timestep
t <- seq(0,100, by = 0.1)

# Variables
theta_init <- c(theta1=0.513, theta2=0, theta3=0)

# Model parameters
params <-
  expand_grid(
    theta_sat = 0.513,
    ds = 0.86,
    nd = 8.5,
    R = 0.00274
    ) %>%
        split(., .$ds)

# Rates of change
theta_rates <- function(t, theta, params) {
  with(as.list(c(theta, params)), {

    dtheta_dt1 = R -(ds*((theta1/theta_sat)^nd)) * (theta1-theta2)
    dtheta_dt2 = ((ds*((theta1/theta_sat)^nd)) * (theta1-theta2)) - ((ds*((theta2/theta_sat)^nd)) * (theta2-theta3))
    dtheta_dt3 = ((ds*((theta2/theta_sat)^nd)) * (theta2-theta3))

    return(list(c(dtheta_dt1,dtheta_dt2,dtheta_dt3)))
  })
}

logistic_solution <-
  map_dfr(
    params,
    ~ode(
    y = theta_init,
    times = t,
    func = theta_rates,
    parms = .x) %>%
  as.data.frame(), .id = "ks")

logistic_solution %>%
  ggplot(aes(time, theta1, col=ks)) +
  geom_line()

logistic_solution %>%
  ggplot(aes(time, theta2, col=ks)) +
  geom_line()

logistic_solution %>%
  ggplot(aes(time, theta3, col=ks)) +
  geom_line()

# Timestep
t <- seq(0,10, by = 0.1)

# Variables
theta_init <- c(theta=0.482)

# Model parameters
params <-
  expand_grid(
    ks = c(0.00021388),
    theta_sat = 0.482,
    nk = 0.007,
    g = 9.8,
    pw = 1000,
    apsi = 1.87,
    npsi = 11.3) %>%
        split(., .$ks)

# Rates of change
theta_rates <- function(t, theta, params) {
  with(as.list(c(theta, params)), {

    dtheta_dt = -(((ks*(theta/theta_sat)^nk)/(g*pw)) * apsi * npsi * theta^(-npsi-1))

    return(list(c(dtheta_dt)))
  })
}

logistic_solution <-
  map_dfr(
    params,
    ~ode(
    y = theta_init,
    times = t,
    func = theta_rates,
    parms = .x) %>%
  as.data.frame(), .id = "ks")

DLSODA-  Warning..Internal T (=R1) and H (=R2) are
      such that in the machine, T + H = T on the next step  
     (H = step size). Solver will continue anyway.
In above message, R1 = 9.93182, R2 = 8.29801e-16
 
DLSODA-  Warning..Internal T (=R1) and H (=R2) are
      such that in the machine, T + H = T on the next step  
     (H = step size). Solver will continue anyway.
In above message, R1 = 9.93182, R2 = 6.27732e-16
 
DLSODA-  Warning..Internal T (=R1) and H (=R2) are
      such that in the machine, T + H = T on the next step  
     (H = step size). Solver will continue anyway.
In above message, R1 = 9.93182, R2 = 4.74105e-16
 
DLSODA-  Warning..Internal T (=R1) and H (=R2) are
      such that in the machine, T + H = T on the next step  
     (H = step size). Solver will continue anyway.
In above message, R1 = 9.93182, R2 = 3.57492e-16
 
DLSODA-  Warning..Internal T (=R1) and H (=R2) are
      such that in the machine, T + H = T on the next step  
     (H = step size). Solver will continue anyway.
In above message, R1 = 9.93182, R2 = 2.69115e-16
 
DLSODA-  Warning..Internal T (=R1) and H (=R2) are
      such that in the machine, T + H = T on the next step  
     (H = step size). Solver will continue anyway.
In above message, R1 = 9.93182, R2 = 2.02247e-16
 
DLSODA-  Warning..Internal T (=R1) and H (=R2) are
      such that in the machine, T + H = T on the next step  
     (H = step size). Solver will continue anyway.
In above message, R1 = 9.93182, R2 = 1.51736e-16
 
DLSODA-  Warning..Internal T (=R1) and H (=R2) are
      such that in the machine, T + H = T on the next step  
     (H = step size). Solver will continue anyway.
In above message, R1 = 9.93182, R2 = 1.13643e-16
 
DLSODA-  Warning..Internal T (=R1) and H (=R2) are
      such that in the machine, T + H = T on the next step  
     (H = step size). Solver will continue anyway.
In above message, R1 = 9.93182, R2 = 8.49653e-17
 
DLSODA-  Warning..Internal T (=R1) and H (=R2) are
      such that in the machine, T + H = T on the next step  
     (H = step size). Solver will continue anyway.
In above message, R1 = 9.93182, R2 = 6.34116e-17
 
DLSODA-  Above warning has been issued I1 times.  
     It will not be issued again for this problem.
In above message, I1 = 10

logistic_solution %>%
  ggplot(aes(time, theta, col=ks)) +
  geom_line()

Parameters

: Saturated soil hydraulic conductivity : Unitless empirical soil parameter

# Timestep
t <- seq(0,10, by = 0.01)

# Variables
theta_init <- c(theta=0)

# Model parameters
params <-
  expand_grid(theta_sat = 0.482,
            R  = 1.0,
            ks = c(40.47, 146),
            c = 4,
            b = 4) %>%
        split(., .$ks)

# Rates of change
theta_rates <- function(t, theta, params) {
  with(as.list(c(theta, params)), {

    dtheta_dt = R*(1-(theta/theta_sat)^b)-ks*(theta/theta_sat)^c

    return(list(c(dtheta_dt)))
  })
}

logistic_solution <-
  map_dfr(
    params,
    ~ode(
    y = theta_init,
    times = t,
    func = theta_rates,
    parms = .x) %>%
  as.data.frame(), .id = "ks")

logistic_solution %>%
  ggplot(aes(time, theta, col=ks)) +
  geom_line()

Now with climatic variability of amplitude = the annual mean rainfall

# Timestep
t <- seq(0,10, by = 0.01)

# Variables
theta_init <- c(theta=0)

# Model parameters
params <-
  expand_grid(theta_sat = 0.482,
            R  = 1.0,
            ks = c(40.47, 5550.37),
            c = 11,
            b = 4) %>%
        split(., .$ks)

# Rates of change
theta_rates <- function(t, theta, params) {
  with(as.list(c(theta, params)), {

    dtheta_dt = (R+R*sin(t/(2*pi)^-1))*(1-(theta/theta_sat)^b)-ks*(theta/theta_sat)^c

    return(list(c(dtheta_dt)))
  })
}

logistic_solution <-
  map_dfr(
    params,
    ~ode(
    y = theta_init,
    times = t,
    func = theta_rates,
    parms = .x) %>%
  as.data.frame(), .id = "ks")

logistic_solution %>%
  ggplot(aes(time, theta, col=ks)) +
  geom_line()

# Timestep
t <- seq(0,10, by = 0.01)

# Variables
theta_init <- c(theta=0)

# Model parameters
params <-
  expand_grid(theta_sat = 0.482,
            R  = 1.0,
            ks = c(40.47),
            c = 11,
            b = 4,
            pe = c(0.5,1,1.4),
            k = 0.46,
            LAI = 0) %>%
        split(., .$pe)


# Rates of change
theta_rates <- function(t, theta, params) {
  with(as.list(c(theta, params)), {

    dtheta_dt = R*(1-(theta/theta_sat)^b)-ks*(theta/theta_sat)^c -
    pe*(exp(-k * LAI)/(1 + exp (-12 * (theta /theta_sat - 0.5))))

    return(list(c(dtheta_dt)))
  })
}

logistic_solution <-
  map_dfr(
    params,
    ~ode(
    y = theta_init,
    times = t,
    func = theta_rates,
    parms = .x) %>%
  as.data.frame(), .id = "pe")

logistic_solution %>%
  ggplot(aes(time, theta, col=pe)) +
  geom_line()

# Timestep
t <- seq(0,10, by = 0.01)

# Variables
theta_init <- c(theta=0)

# Model parameters
params <-
  expand_grid(theta_sat = 0.482,
            R  = 1.0,
            ks = c(40.47),
            c = 11,
            b = 4,
            pe = c(0.5, 1,1.4),
            k = 0.46,
            LAI = 0) %>%
        split(., .$pe)


# Rates of change
theta_rates <- function(t, theta, params) {
  with(as.list(c(theta, params)), {

    dtheta_dt = (R+R*sin(t/(2*pi)^-1))*(1-(theta/theta_sat)^b)-ks*(theta/theta_sat)^c -
    pe*(exp(-k * LAI)/(1 + exp (-12 * (theta /theta_sat - 0.5))))

    return(list(c(dtheta_dt)))
  })
}

logistic_solution <-
  map_dfr(
    params,
    ~ode(
    y = theta_init,
    times = t,
    func = theta_rates,
    parms = .x) %>%
  as.data.frame(), .id = "pe")

logistic_solution %>%
  ggplot(aes(time, theta, col=pe)) +
  geom_line()

Evaporation should occur only in the top 10 cm of soil https://pure.mpg.de/rest/items/item_1781494/component/file_1786328/content

is defined as:

Where the diffusivity, is defined as:

and the hydraulic conductivity is defined as:

and (unitless) are empirical parameter which vary with soil type, is acceleration due to gravity and is the density of water . Finally, is the soil water potential.

Because the soil water potential at a given depth is related to soil moisture content according to the following equation:

where and are soil-dependent empirical parameters. It follows that diffusivity can be calculated in terms of soil moisture content at a given depth according to the following equation:

Thus, equals:

# Timestep
t <- seq(0,100, by = 1)

# Variables
theta_init <- c(theta=0.482)

# Model parameters for silty loam (Landsberg)
params <-
  expand_grid(
    #convert to day
    ksat = c(12.2*24),
    nk = 11.9,
    theta_sat = 0.482,
    g = 9.8,
    pw = 1000,
    apsi = 1.87,
    npsi = 4.5) %>%
        split(., .$ksat)

# Rates of change
theta_rates <- function(t, theta, params) {
  with(as.list(c(theta, params)), {
    soil_conductivity = ksat * (theta/theta_sat)^nk
    dpsi_dtheta = apsi * npsi * theta ^ (-npsi-1)
    # dtheta_dt = - (soil_conductivity/(g*pw))*dpsi_dtheta*((theta-0.2)/0.1)
      dtheta_dt = - (soil_conductivity)

    return(list(c(dtheta_dt)))
  })
}

logistic_solution <-
  map_dfr(
    params,
    ~ode(
    y = theta_init,
    times = t,
    func = theta_rates,
    parms = .x) %>%
  as.data.frame(), .id = "ks")

logistic_solution %>%
  ggplot(aes(time, theta, col=ks)) +
  geom_line()

Key technologies used to build the plant package

Rich FitzJohn & Daniel Falster — Tue, 23 Feb 2016 00:00:00 GMT

Originally published on the Methods in Ecology and Evolution Methods blog on 23 February 2016, by Rich FitzJohn and Daniel Falster, and reposted here in the Overstorey notebook. It accompanies the package’s methods paper, Falster et al., doi:10.1111/2041-210X.12525.

Our paper in Methods in Ecology and Evolution describes a new software package, plant. plant is an individual-based simulation model that simulates the growth of individual trees, stands of competing plants, or entire metacommunities under a disturbance regime, using common physiological rules and trait-based functional trade-offs to capture differences among species.

Non-linear processes and thousands of plants

Since the development of gap models in the 1970s (e.g. Botkin 1972), researchers have been using computer simulations to investigate how elements of plant biology interact with competition and disturbance regimes to influence vegetation demography, structure and diversity. Simulating the competitive interactions among many thousands of plants, however, is no easy task.

Despite widespread recognition of the importance of key non-linear processes — such as size-structured competition, disturbance, and trait-based trade-offs — for vegetation dynamics, relatively few researchers have been brave (or daft) enough to try and incorporate such processes into their models. The situation is most extreme in theoretical ecology, where much contemporary theory (e.g. coexistence theory, neutral theory) is still built around completely unstructured populations.

Features of `plant`

Key processes modelled within the plant package.

The plant package attempts to change that by providing an extensible, open source framework for studying trait-, size- and patch-structured dynamics. One thing that makes the plant model significant is the focus on traits. plant is one of several attempts seeking to integrate current understanding about trait based trade-offs into a model of individual plant function (see also Moorcroft et al. 2001, Sakschewski et al. 2015).

A second feature that makes the plant software significant is that it is perhaps the first example where a computationally intensive model has been packaged up in a way that enables widespread usage, makes the model more usable and doesn’t sacrifice speed.

In this post we will describe the key technologies used to build the plant software.

Overcoming the speed/generality trade-off

R has become a widely used language in ecology and evolution, but it’s not ideal for building individual based simulations, due to its relatively low speed. The solution to this has traditionally been to write simulations in a lower-level compiled language (such as C, C++ or Java), have the simulation write output to files, and analyse those with R or a higher-level language (indeed that is the direction originally taken with this model). This traditional approach leads to a strong speed/flexibility trade-off. This trade-off arises because of:

the need to write code to generate and parse the output files
the need to include options for parsing all sorts of arguments in your C++ code
the need to regularly recompile the C++ code whenever you want to add an option
the inability to exploit R’s built-in functions (e.g. for probability distributions or integration, for non-time sensitive elements of the code)

Overall, having separate code for running the model and analysing model output greatly reduces flexibility in interacting with the model.

In plant, we wanted the best of both worlds – a simulation that would run at the speed of a compiled language but would allow us to interact with every part of the model. We wanted to be able to simulate our metacommunity of many species with 1000’s of plants and then drill down and inspect the physiological details of any individual plant. At the same time, we wanted the machinery to be flexible enough to allow us to swap out the low-level physiological model of the plants used while keeping the higher level behaviour the same.

We implemented the core of the model in C++, because code written in C++ can be much faster than code written in R. In our C++ code, we have plants that are grouped together into species, which exist in patches. They interact with a common light environment, and the whole system is controlled by a rather large set of parameters. Exposing these to R is a challenge because this modelling style relies on a fundamentally different approach to dealing with exposing data to R (in this style of C++ objects modify themselves, whereas in R objects are generally immutable with function calls creating new objects).

To bridge this divide we combined two new technologies in R; Rcpp and R6 classes with a new package of our own making, RcppR6. This allows us to export a “pointer” to our C++ objects to R, and interact with it using the same set of methods that are available on the C++ side. As these objects contain other objects (species contain plants, etc) we had to create interfaces for all of our objects, which we did using a code generation approach. We first describe the interface for each object type we want to interact with. For example, here is the interface for our basic “plant” type. The RcppR6 package then generates a lot of boilerplate code required to export the objects to R and back again (boilerplate are sections of code that have to be included in many places with little or no alteration).

The RcppR6 package reduces the amount of interface code you need to write when linking C++ with R.

We used a “generic programming” approach to allow for different physiologies; plants provide particular methods (such as reporting their height, growth rate, etc) and they can be used with any of the higher level functions (such as the SCM algorithm, or tools to grow plants to a different size). For example, this file implements a function to compute the whole plant light compensation point for any given plant type T. The C++ compiler establishes that each plant type that the function is used with can be used and generates appropriate code for each.

On the R side, we use R’s simple “S3” generic programming system to dispatch to the appropriate compiled function based on the type of the plant used. We think this mix of compile-time polymorphism and run-time polymorphism could enable efficient models and expressive bindings from dynamic languages.

Overall our approach allowed us to have both the expressiveness and interactivity of a dynamic language with the speed of C++. When running a simulation almost all the code runs at compiled speed, with R (which has a reputation for being slow) idle. But when the time comes to analyse our work with the outputs of the model, we can directly access any part of the simulation. We exploit this ability to interact with the model at any level in the vignettes for the package.

You can see some code using the plant package, in Appendix S3 of our paper.

Version control facilitates seamless collaboration

Increasingly, scientists are recognising the virtues of serious version control. We use git and, as we were early adopters, the entire history of development for plant has been tracked under version control. Alongside git, we used the code-sharing website GitHub to host our git repository. GitHub facilitates seamless collaboration by:

providing a nice interface for seeing who changed what and when
keeping older versions of the code
allowing users (including ourselves) to report potential issues
allowing others to clone the package and make changes

This track-record of what changed when was invaluable to us as we tracked down bugs and regressions and for working on code collaboratively.

Regular testing saves time in the long run

Models as large as this require a lot of testing to be sure that they are correct. Until recently, this testing process tended to be manual. As researchers develop models they will usually test them extensively, but these tests generally do not get stored for future use.

We made use of the testthat package to run a large set of automated tests (1307 at last count) covering all aspects of the model from validating inputs to the behaviour of the model in known pathological parts of parameter space. We combine this test suite with Travis CI — an automated testing service — to ensure that the tests are run every time someone makes a change to the code (and we all get an email if someone breaks it).

Pushing changes in our code to GitHub automatically triggers a bunch of tests to run via Travis CI. We get notified if we inadvertently broke any core functionality.

This test-driven-development approach has allowed us to swap out large parts of the package as we developed it and changed our minds about direction. We can run any changes through the test suite, so we can be reasonably sure we haven’t broken any previous behaviour. While testing is not a panacea it allowed us to be much more confident than we would otherwise have been in making changes to the model.

We strongly encourage other groups writing simulation models to consider testing from the outset as we believe it saves time in the long run.

R packages: easy installation and distribution

Using R brings many benefits beyond ease of analysis. Specifically, there are well established processes for installing packages, making it easy to deploy software across diverse platforms. While many packages are deployed via R’s core packaging system CRAN, packages can also be directly installed from GitHub using the handy devtools package.

Installing plant should be as easy as running these lines of code:

install.packages("devtools")
devtools::install_github("traitecoevo/plant", dependencies = TRUE)

(unfortunately we are waiting on updates to the R/Windows compiler toolchain for this to work on Windows.)

From then on, all you need to do is run library(plant) and you’re ready to use our model. Running library(help = plant) from within R will display all the help files for the project.

Conclusion

As simulation models become more common place in ecology, we modellers should move beyond implementing one-off models that work locally but use bespoke interfaces and arbitrary command line arguments to run. We hope that plant, with its extensible interface and combination of compiled-language speed and dynamic language flexibility, will be a useful starting point for further research in this space.

To find out more about plant, read Plant: A package for modelling forest trait ecology & evolution by Falster et al. (2015). This article was part of the British Ecological Society’s Cross-Journal Special Feature, Demography Beyond the Population. You can also read the original post on the MEE Methods blog.

Overstorey

Moving cohort refining into C++

The problem

The key insight

How it was done — four behaviour-preserving phases

What callers see now

Follow-ups outside this repo

Making root water uptake fast

What was achieved

What the model is, and why it was a hotspot

The optimisation phases

Key innovations

Measured outcome

A reference prototype for root water uptake

Test

Reviewing the TF24 leaf model code

What changed, by class of finding

Key takeaways

Where the detail lives

Optimising the FF16 hot paths

Headline numbers

Where the time was going

How it was done

Notes on measurement discipline

A soil-water bucket model from AWRA-L

Load packages

Load observational data

Prepare observational data

Number of soil layers

Frost, A. J., and Shokri, A., (2021) The Australian Landscape Water Balance model (AWRA-L v7). Technical Description of the Australian Water Resources Assessment Landscape model version 7. Bureau of Meteorology Technical Report

Melton et al., (2017) Tiling soil textures for terrestrial ecosystem modelling via clustering analysis: a case study with CLASS-CTEM (version 2.1) depending on

Cosby et al. (1984) A Statistical Exploration of the Relationships of Soil Moisture Characteristics to the Physical Properties of Soils

Functions

Soil water model

Ode solver

Parameters

cpp implementation

Minimise rmse

Minimise bias

Delta bare soil example

Hydraulics inner-loop benchmark

Per-post environment

The sweep

Reproducibility footer

When the Richards equation fights back

The model

The instability

The fix: an implicit solver

Why this happens

Takeaways for the soil-water work

References

Prototyping a soil water-balance bucket model

Key technologies used to build the plant package

Non-linear processes and thousands of plants

Features of plant

Overcoming the speed/generality trade-off

Version control facilitates seamless collaboration

Regular testing saves time in the long run

R packages: easy installation and distribution

Conclusion

Features of `plant`