# Seed and root–soil lab, version 2

## Fine particle and performance revision (2026-11-12)

The second version adds selectable physical contact-particle scales: balanced
(radii .11–.50 mm), fine (.08–.38 mm), and ultra (.055–.27 mm). The packing is
still a disordered set of spherical inclusions in an unresolved soil matrix;
these are numerical resolution choices, not measured mineral-size distributions.
Legacy version-1 checkpoints retain their original coarse packing on import.
Root contact search uses a hash scaled to particle diameter and swept capsules.
Confinement now has an illustrative elastoplastic rest position: the elastic
matrix force yields at `kn min(.008 mm, .08 r) (1 + 2 compaction)`. Beyond yield,
the rest position follows the particle; the original position is retained. This
avoids a purely elastic anchor pulling a rearranged grain back into a blocked
root tip indefinitely. Ten local relaxation iterations use mobility
`.5 / (kn (1 + contactCount) + anchorStiffness)` with bounded displacements.
This phenomenological yield law is uncalibrated; it adds irreversible
rearrangement, not a measured plasticity or capillary-force model.
Surface facets and microscopic specks are deterministic visual detail, excluded
from force and water calculations. The UI reports contact-particle counts.

The hydraulic equations, biological timestep and mass balance are unchanged.
The solver stores face connectivity in typed arrays and shares constitutive
powers to avoid allocation and redundant work. Worker batches have a wall-time
budget; their completed fixed steps are reported, with no biological time dropped.
GPU uploads append new root segments and update only displaced contact particles.
Water and root snapshots use transferable buffers. Rendering has its own cadence;
pause and restart remain available while the Worker is busy.

Spec authored before implementation, 2026-11-12. This is a separate, reusable
JavaScript model and Worker under `root-lab/`, alongside the existing mycelium
simulator. The earlier `plant_root_v1` protocol and saved scenarios are unchanged.
All implementation is original, derived from these equations and papers. No
CPlantBox/CRootBox source code was consulted.

## Scientific status

This is an interactive, mechanistic **research prototype**, not a calibrated
species model or a validated high-fidelity soil solver. It resolves a 3D root
graph, continuum soil water, and explicit contact particles. Particle size is
not the mineral grain-size distribution of the selected hydraulic texture.
Finer visualization does not imply greater predictive accuracy.

## State and units

Space: mm; biological time: h; water volume: mm³ = µL; pressure: MPa = N/mm²;
contact force: N; temperature: °C. Positive y is depth. The sealed rhizobox is
36 × 54 × 18 mm. The root origin is (0, 3, 0) mm. Float64 soil water, root graph,
particle positions, original anchors and plastic rest positions, seed hydration, accumulated hydrothermal time,
branch sites, RNG state, inputs and mass ledger are serialized.

## Germination [R1]

For a single representative seed, accumulate
`H += max(0, min(T, To) − Tb) × max(0, ψ − ψb(T)) × fO2 × dt`,
where `ψb(T) = ψb + kT max(0, T − To)`. No accumulation at or above Tc.
Radicle emergence requires `H ≥ Hrequired` and hydration ≥ 0.85.
Water-limited imbibition follows a first-order approach to equilibrium;
the actual soil sink supplies the change in hydration. This imbibition law and
oxygen multiplier are explicit extensions, not equations fitted in R1.

Defaults (illustrative, uncalibrated): Tb = 5, To = 25, Tc = 40 °C;
ψb = −0.6 MPa; kT = 0.04 MPa/°C; Hrequired = 180 MPa·°C·h;
hydration time = 3 h; imbibition capacity = 0.8 µL. Tb/To/Tc and thresholds
must be measured for a seed lot before prediction. No population distribution,
dormancy, seed mortality or gene regulation is claimed.

## Soil hydraulics [R2, R3]

`Se = (θ − θr)/(θs − θr)`; `m = 1 − 1/n`;
`h = −(Se^(−1/m) − 1)^(1/n)/α` (mm),
`ψ = h × 9.80665e−6` MPa,
`K = Ks sqrt(Se) [1 − (1 − Se^(1/m))^m]^2` (mm/h).

Face flux from i to j is `Kij ((hi − hj)/dx + gravity)`;
Kij is the harmonic mean. Gravity = 1 for a downward face, zero otherwise.
Finite volumes exchange equal and opposite amounts. Closed exterior boundaries;
no evaporation or drainage. Irrigation enters top cells; excess is recorded as
runoff. Uptake cannot remove residual water. Seed water and root uptake are
separate sinks in the mass ledger.

The solver substeps at ≤ 0.02 h, using linearized backward Euler for all cells
simultaneously. `C = dθ/dh`; face conductance `a = Kij dt/dx²` builds the symmetric
matrix `(C + dt L_K) δh = −dt L_K(h − depth)`. Jacobi-preconditioned conjugate
gradients solve to maximum cell residual 1e−11 (120 iterations maximum; reject
above 1e−7). Final face fluxes from `h + δh` are applied in equal and opposite
pairs. The maximum linear residual is serialized. This uses one linearization
per substep, rather than converged nonlinear Picard iteration. Transfers are
also bounded by donor water and receiver capacity; limited transfers are counted
and displayed. This positivity limiter preserves mass but modifies fluxes when
active. Wet fronts and saturation require timestep/grid convergence and a fully
converged implicit Richards benchmark. This is not a validated Richards solver.
Numerical head evaluation clips Se to [1e−5, 1−1e−6].

Hydraulic texture defaults from R3 (α converted cm⁻¹ to mm⁻¹; Ks cm/day to mm/h):

| Texture | θr | θs | α /mm | n | Ks mm/h |
|---|---:|---:|---:|---:|---:|
| Sand | .045 | .43 | .0145 | 2.68 | 297 |
| Loam | .078 | .43 | .0036 | 1.56 | 10.4 |
| Clay loam | .095 | .41 | .0019 | 1.31 | 2.6 |

## Architecture and stress [R4, R5]

Primary and lateral axes have persistent tips, basal and apical exclusion zones,
distance-spaced branch sites and a maturation delay. Laterals emerge from old
nodes, not by splitting the advancing tip. Radius and maximum extension decline
with order (maximum order 3). Direction integrates gravitropism, local water
gradient, aggregate avoidance and seeded angular variability per emitted segment.
Growth increments accumulate until the spatial segment resolution is reached.

`v = vmax × 0.65^order × fT × fwater × fO2 × exp(−ln(2) Q/Q50)
 × max(0, 1 − Laxis/Lmax) × freserve`.
`fwater = clamp((ψ + 1.5)/1.48, 0, 1)`;
`fO2 = clamp((θs − θ)/0.10, 0, 1)`.
Q is an empirical penetration-resistance proxy (MPa), increasing with selected
compaction, drying and the optional compacted layer. Q50 = 1.5 MPa is an
illustrative value within the 0.8–2 MPa range discussed by R5; it is not a fitted
parameter. Penetrometer resistance and aggregate contact stress are distinct.

Defaults: vmax = 1.2 mm/h; primary radius .23 mm; lateral radius multiplier .65;
primary Lmax = 100 mm; branch spacing 2.4 mm; basal zone 2 mm; apical zone 3 mm;
maturation delay 8 h; insertion angle 60°; reserve 1,200 mm of equivalent primary
root production. Reserve consumption scales with cross-sectional area. No shoot
assimilation, vascular network hydraulic solution or nutrient transport is claimed.
Segment water uptake uses radial area and a prescribed xylem potential −0.25 MPa,
with conductivity 0.004 mm/(h·MPa). This is a sink proxy, not whole-plant hydraulics.

## Aggregate mechanics [R6]

Polydisperse spheres are explicit inclusions in the unresolved continuum
matrix. Spatial hashing finds sphere–sphere and swept root capsule–sphere
contacts. Linear normal penalty `Fn = kn max(0, R − distance)`; displacement
opposing tangential growth is capped by `μ Fn` (Coulomb sliding approximation).
Elastoplastic matrix rest positions supply confinement. Several overdamped, displacement-capped
relaxation iterations propagate contact forces locally before a root increment
is accepted. Blocked increments remain pending; roots steer around obstacles.
Roots cannot tunnel across spheres or box boundaries.

Defaults: kn = 0.08 N/mm; μ = .35; anchor stiffness scales with compaction;
fine sampling strata .92 mm; radii .08–.38 mm with rejection of overlaps;
10 relaxation iterations; maximum accepted penalty overlap
`min(.025 mm, .2 × minimum particle radius)`. The other resolutions and yielding
rule are specified above. Force is recorded in N. Relaxation iterations
are a numerical pseudo-time, not biological hours. This is a quasi-static penalty
model inspired by granular contact mechanics, not a reproduction of R6's DEM.
Rotational DOFs, tangential spring history, inertia, cohesion, resolved capillary
bridges, particle breakage, root bending elasticity and hydraulic porosity feedback
are absent. Their calibration and coupling are necessary for a high-fidelity DEM.

## Reproducibility and validation

The Worker owns the model; rendering never changes it. Playback speed only
changes the number of fixed 0.1 h steps. Seeded RNG, event log and full checkpoint
support identical continuation in the same JS runtime and model version. Version-1
imports retain packing and state but continue with the version-2 contact law.
Versioned import validates
finite values, bounds, graph references and buffer sizes before replacing a run.

Automated gates: deterministic replay and restored continuation; temperature and
water germination inhibition; retention monotonicity; mass conservation including
irrigation, runoff, seed imbibition and uptake; donor/capacity bounds; stress
response; basal/apical branch rules; swept collision and contact response; fine
packing and sustained growth; neighbor load propagation; graph and box integrity;
legacy migration; transferable packet ownership; malformed checkpoint rejection.
Browser checks cover start, pause, stepping, restart during playback, overlays,
close-up inspection, Ultra export/import and narrow layouts.

Before predictive use: seed-lot hydrothermal fits; measured root trajectories;
penetrometer curves; triaxial/penetration calibration of aggregate contacts;
Richards analytic/reference benchmarks; independent soil moisture and root uptake
data; grid, time and mechanical iteration convergence; performance characterization.

## Sources (accessed 2026-11-12)

- R1: Alvarado & Bradford (2002), *A hydrothermal time model explains the cardinal
  temperatures for seed germination*. https://doi.org/10.1046/j.1365-3040.2002.00894.x
- R2: van Genuchten (1980), *A closed-form equation for predicting the hydraulic
  conductivity of unsaturated soils*. https://doi.org/10.2136/sssaj1980.03615995004400050002x
- R3: Carsel & Parrish (1988), *Developing joint probability distributions of soil
  water retention characteristics*. https://doi.org/10.1029/WR024i005p00755 ; parameter
  table reproduced in the USDA-hosted SWMS manual, Table 4:
  https://www.ars.usda.gov/ARSUserFiles/20360500/pdf_pubs/P1228.pdf
- R4: Schnepf et al. (2018), *CRootBox: a structural–functional modelling framework
  for root systems*. https://doi.org/10.1093/aob/mcx221 (paper only).
- R5: Bengough et al. (2011), *Root elongation, water stress, and mechanical impedance*.
  https://doi.org/10.1093/jxb/erq350
- R6: Fakih, Delenne, Radjai & Fourcaud (2019), *Root growth and force chains in a
  granular soil*. https://doi.org/10.1103/PhysRevE.99.042903 ;
  https://arxiv.org/abs/1811.09342