WEPPcloud

← Back to help

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 as nan.
  • SSURGO horizon construction could serialize invalid field_cap/wilt_pt values if source or Rosetta-derived candidates were non-finite or sentinel values.
  • WeppSoilUtil could parse and reserialize invalid legacy fc/wp values, including during 9002 conversion.

New behavior:

  • Local fc/wp validation requires finite values and 0 <= wp <= fc <= 1.
  • SSURGO generation falls back to Rosetta for the pair when SSURGO-derived values fail validation.
  • WeppSoilUtil validates 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/fc values 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

  1. Change wepppy.all_your_base.isfloat() to reject nan and inf - rejected because the helper is global and may be used where "convertible to float" is the intended predicate.
  2. Let WEPP fail and only document affected runs - rejected because the generated input is invalid and can be repaired deterministically before execution.
  3. Drop SSURGO source water-content fields entirely and always use Rosetta - rejected because valid SSURGO water-content data remains the preferred source.
  4. 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 wp and fc multipliers.

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 with wepp_260606_hill return code -8 and -9.9 nan soil rows.
  • WEPP source evidence: /workdir/wepp-forest_260430_baseline/src/input.for reads thetd2, and later water-balance paths consume derived thetd1/thetfc.
  • Regression tests: tests/soils/test_ssurgo_fc_wp_sanitization.py and tests/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.