ADR-0022: Alex Static Ash-Transport Increment
Status: Accepted Date: 2026-07-18 Review Date: 2026-08-18
Context
The Watanabe/Alex ash model exposes a static exponential transport mode with
initial transport capacity A in tonne ha⁻¹ mm⁻¹ and depletion coefficient
B in mm⁻¹. The implementation introduced in September 2025 passed the array
slice cum_ash_runoff_mm[:i] to scalar math.exp, used an ambiguous sign and
parenthesis convention, and failed when a runoff event occurred after the slice
contained multiple values.
The defect became production-visible after the July 2026 selector-propagation
fix began honoring ash_model=alex and transport_mode=static from the UI.
Decision
For each daily ash-runoff increment, static transport is:
delta_M = (A / B) * [exp(-B * Q_previous) - exp(-B * (Q_previous + delta_Q))]
Q_previous is the scalar cumulative ash runoff through the previous timestep,
cum_ash_runoff_mm[i - 1], and delta_Q is the current timestep's ash runoff,
ash_runoff_mm[i]. The result is a nonnegative daily transport increment in
tonne ha⁻¹ before the existing available-ash clipping is applied.
Decision Provenance
Decision Venue: Codex maintenance conversation, 2026-07-18 22:38 PDT Participants Present: WEPPpy requesting maintainer, Codex Decision Owner(s): WEPPpy requesting maintainer Implementer(s): Codex
Change Summary
Previously, the static branch evaluated an array in math.exp, did not multiply
the current runoff increment by B inside the exponent, and placed the
exponential terms in an order that did not express a nonnegative depletion
increment. The new implementation evaluates two scalar cumulative-runoff
states and subtracts the later state from the earlier state.
Output columns, units, parquet schemas, controller state, and request fields are unchanged. Only Watanabe/Alex static-mode transport values change; Watanabe/Alex dynamic mode and the Srivastava model retain their existing calculations.
Rationale
The selected equation integrates the exponentially depleted capacity between the previous and current cumulative-runoff states. It preserves the declared units, returns zero for zero runoff, remains nonnegative for nonnegative runoff, and decreases for equal runoff increments as cumulative runoff increases.
Alternatives Considered
- Replace
[:i]with[i]only - rejected because the current cumulative value is not assigned until later in the timestep and the sign and parenthesis defects would remain. - Apply NumPy exponentiation to the historical slice - rejected because the model requires one daily scalar increment, not a vector of all prior states.
- Disable static mode - rejected because static Watanabe transport is an explicitly supported and required workflow.
Consequences
Previously failing Alex/static jobs can be rerun without state migration. Their transport results will differ from any output produced by workarounds based on the invalid expression. Static-mode results remain subject to the existing available-ash clipping, decomposition, wind, and mass-balance logic.
Evidence
docs/projects/nasa-roses-utility-watersheds/watar-integration-plan.md- Forest baseline RQ job
67d03de4-4b15-4f72-a428-470571021bd4, which reproduced the production array-to-scalar failure on 2026-07-18. - Forest verification RQ job
b8f5d3ee-e45a-48fd-874e-3c3d839ed807, which finished in 59.1 seconds and generated 106 hillslope parquet files plus five post-processing parquet datasets on 2026-07-18. tests/nodb/mods/test_ash_multi_year_model_alex_static.py
Risk and Rollback Notes
The primary risk is a mismatch between the approved equation and independently expected Watanabe static-mode results. Monitor exact test vectors and cloned-run outputs. Rollback should revert this ADR and the formula together; do not restore the array expression or silently switch affected runs to dynamic or Srivastava mode.
Implementation Notes
Keep the formula in a private scalar helper so exact vectors can test it without running the full hillslope simulation. Full-path regression coverage must also exercise cumulative runoff, clipping, dynamic-parameter independence, and mass balance through the model loop and a real RQ worker job.