ADR-0016: AgFields Applied-Residue hmax Floor
Status: Accepted Date: 2026-07-10
Context
The sacral-self-discipline AgFields acceptance run uses ten managements
generated by Jim's plant-management interface. Every source contains an applied
residue plant named L179_weed whose hmax, cuthgt, rdmax, and xmxlai are
zero. Once rotation scenario overflow was fixed, wepp_260430_hill rejected the
referenced residue plant with HMAX <= 0.0 before simulation.
The plant is referenced by residue-addition operations (pcode 10) but is not
used as an active crop or initial-condition plant. WEPP nevertheless validates
all referenced plant definitions. The maintainer identified this as systematic
interface output and authorized normalization during AgFields ZIP ingestion.
Decision
During AgFields plant ZIP ingestion, set hmax to 0.00001 m when all of the
following are true:
- the parsed value is nonpositive;
- the plant is referenced by a cropland residue-addition operation (
pcode10 or 12); and - the plant is not referenced as a yearly active plant or an initial-condition plant.
Apply the rule to both 2017.1 inputs before downgrade and raw 98.4 inputs before final installation. Preserve original 2017.1 files unchanged and record the normalization in additive inventory provenance. Do not normalize by scenario name and do not change any other plant or operation parameter.
Decision Provenance
Decision Venue: Codex API conversation, 2026-07-10 13:06 PDT Participants Present: Roger Lew, Codex Decision Owner(s): Roger Lew, WEPPpy maintainer Implementer(s): Codex
Change Summary
Old behavior: Jim-interface residue-only plants with hmax=0 were accepted as
parse-valid and installed unchanged; WEPP later rejected them.
New behavior: qualifying residue-only plants are installed with
hmax=0.00001 m. 0.00001 is the smallest positive value preserved by the
five-decimal management serializer. The original source value and applied floor
are retained in provenance.
Rationale
The floor satisfies WEPP's strict positive-input contract while adding the
smallest representable artificial height. Restricting the rule to residue-only
references ensures the fallback does not parameterize a growing crop. Semantic
reference analysis is more robust than coupling behavior to Jim's current
L179_weed name.
Alternatives Considered
- Reject the archive and require re-export - rejected because the zero-height placeholder is systematic interface output and the maintainer requested compatible ingestion.
- Use
0.01 mor copy the active crop height - rejected as larger and less neutral arbitrary parameterizations. - Normalize every nonpositive plant height - rejected because it could hide an invalid active-crop definition.
- Patch WEPP validation - rejected because this is an input compatibility defect and weakening global validation would affect unrelated workflows.
Consequences
Newly ingested final management files differ from their source for one narrowly
qualified field. Existing projects are unchanged until reprocessing. The
fallback clears the observed HMAX <= 0 validation error, but it does not claim
the entire management is valid; current replay subsequently reaches an
independent zero-random-roughness SIGFPE in frcfac, which remains outside this
decision.
Evidence
docs/work-packages/20260710_management_rotation_synth_hardening/- Run
/wc1/runs/sa/sacral-self-discipline, sub-field 3733. - All ten preserved 2017.1 source managements contain the same zero-height residue placeholder.
- Real-binary probes show both
0.00001 mand0.01 mclear thehmaxvalidation; the smaller serialized value is selected.
Risk and Rollback Notes
Risk is bounded by residue-only reference gating and explicit provenance. Roll
back if the interface begins using these scenarios as active crops, if WEPP uses
hmax in residue-addition calculations, or if comparison runs show a material
output effect. Revert the helper and restore final files from preserved 2017.1
sources; additive provenance needs no migration.
Implementation Notes
Regression coverage must exercise both input formats, prove active plants are untouched, and replay the exact p3733 schedule. Do not normalize the separate zero random-roughness operation exposed after this floor.