ADR-0012: SSURGO Field Capacity and Wilting Point Sanitization
Status: Accepted
Date: 2026-07-06
Review Date: 2026-08-06
Context
NASA ROSES batch runs under /wc1/batch/nasa-roses-202606-psbs/ generated WEPP soil files with invalid legacy water-content values such as -9.9 nan in the fc wp columns. WEPP hillslope jobs failed with wepp_260606_hill return code -8 and a Fortran SIGFPE while reading soil input. The WEPP source uses the read values after input parsing, so this is a model-input validity issue rather than harmless parsing residue.
Decision
WEPPcloud will treat SSURGO/WEPP field capacity and wilting point as valid only when both values are finite volumetric water-content fractions and satisfy 0 <= wp <= fc <= 1. SSURGO horizon construction will continue to prefer SSURGO wthirdbar_r and wfifteenbar_r values adjusted for rock content, but if the resulting pair is invalid it will replace both values with Rosetta predictions and record a build note. Generic WEPP soil serialization will enforce the same rule and fail explicitly if invalid values reach it.
The 2026-07-10 amendment applies the seeded soil/landuse generator's existing
profile boundary clamp to every mutation profile before serialization. The
baseline and edge profiles use the existing broad physical bounds; targeted
profiles retain their existing narrower bounds. This prevents independent
wp and fc multipliers from producing wp > fc, including in later OFEs of
multi-OFE seed soils. No bound or multiplier value changed.
Decision Provenance
Decision Venue: Codex operator session for production batch failure, 2026-07-05 22:11 PDT
Participants Present: Roger Lew, Codex
Decision Owner(s): Roger Lew / WEPPcloud maintainer
Implementer(s): Codex
Amendment Decision Venue: Codex operator session, 2026-07-10 17:45 PDT
Amendment Participants Present: Roger Lew, Codex
Amendment Decision Owner(s): Roger Lew / WEPPcloud maintainer
Amendment Implementer(s): Codex
Change Summary
Old behavior:
isfloat()accepted strings or floats such asnan.- SSURGO horizon construction could serialize invalid
field_cap/wilt_ptvalues if source or Rosetta-derived candidates were non-finite or sentinel values. WeppSoilUtilcould parse and reserialize invalid legacyfc/wpvalues, including during 9002 conversion.
New behavior:
- Local
fc/wpvalidation requires finite values and0 <= wp <= fc <= 1. - SSURGO generation falls back to Rosetta for the pair when SSURGO-derived values fail validation.
WeppSoilUtilvalidates Rosetta recomputation and rejects invalid legacy values before writing 7778/900x soil rows.- Every seeded mutation profile applies the already-defined horizon boundary
clamp before writing, so independently mutated
wp/fcvalues preserve the serializer contract across every OFE.
Rationale
The chosen range matches the model contract for volumetric water-content fractions and catches every observed production failure mode: nan, inf, negative sentinels such as -9.9, values above one, and inverted wp > fc pairs. Local validation avoids a broad change to isfloat() while giving this model-input path explicit physical semantics.
Alternatives Considered
- Change
wepppy.all_your_base.isfloat()to rejectnanandinf- rejected because the helper is global and may be used where "convertible to float" is the intended predicate. - Let WEPP fail and only document affected runs - rejected because the generated input is invalid and can be repaired deterministically before execution.
- Drop SSURGO source water-content fields entirely and always use Rosetta - rejected because valid SSURGO water-content data remains the preferred source.
- Repair only the failing multi-OFE fixture - rejected because the inversion
is generated by production mutation logic and can affect any OFE/profile
combination using independent
wpandfcmultipliers.
Consequences
Valid SSURGO water-content values keep the existing parameterization. Invalid values are replaced with Rosetta estimates, which may differ from SSURGO where the source data is corrupt or sentinel-filled. If Rosetta also returns invalid values, WEPPcloud fails before writing the soil file, producing a Python error with horizon context instead of a later WEPP SIGFPE.
Evidence
- Work package:
docs/work-packages/20260705_ssurgo_fc_wp_sanitization/package.md - Production failure signature:
/wc1/batch/nasa-roses-202606-psbs/runids withwepp_260606_hillreturn code-8and-9.9 nansoil rows. - WEPP source evidence:
/workdir/wepp-forest_260430_baseline/src/input.forreadsthetd2, and later water-balance paths consume derivedthetd1/thetfc. - Regression tests:
tests/soils/test_ssurgo_fc_wp_sanitization.pyandtests/wepp/soils/utils/test_wepp_soil_util.py. - Seeded generator regression:
tests/wepp/test_seeded_soil_landuse_generators.py::test_generate_case_preserves_multi_ofe_soil_structure.
Risk and Rollback Notes
Risk: some unusual historical soil files with out-of-range water contents will now fail before serialization. This is intentional for WEPP model safety. Rollback is to revert the sanitizer and serializer validation commits, but rollback should only be used if validated scientific workflows require a broader water-content range and a new ADR revises the accepted bounds.
Implementation Notes
Keep the core guard local to SSURGO and WEPP soil utility code, and require
seeded generators to satisfy it before serialization. Do not alter the global
isfloat() helper for this incident. Production batch invalidation must remove
build_soils and downstream task timestamps only after fixed worker code is
deployed.