WEPPcloud

← Back to help

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 (pcode 10 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

  1. Reject the archive and require re-export - rejected because the zero-height placeholder is systematic interface output and the maintainer requested compatible ingestion.
  2. Use 0.01 m or copy the active crop height - rejected as larger and less neutral arbitrary parameterizations.
  3. Normalize every nonpositive plant height - rejected because it could hide an invalid active-crop definition.
  4. 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 m and 0.01 m clear the hmax validation; 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.