WEPPcloud

← Back to help

ADR-0006: Observed-Daymet Radiation TOA Normalization

Status: Accepted Date: 2026-06-06 Review Date: 2027-06-06

Context

Observed-Daymet climate production for /wc1/runs/in/indispensable-presenter generated daily solar radiation values that downstream openWEPP rejected before WBVAL03 could reach its snowmelt/water-balance validation surface. The observed failure was: CLIM-RUNTIME-E-017, radly=486, with the accepted domain 0 <= radly <= baseline sunmap horizontal daily potential (rpoth/r3).

WEPPpy's observed-Daymet single-location producer converts Daymet daylight average srad(W/m^2) to srad(l/day) using srad * dayl / 41840, then writes that value into the WEPP CLI rad field. Static evidence showed the generated CLI values match Daymet-derived srad(l/day) after integer publication rounding. For indispensable-presenter, 53 of 2191 rows exceeded the baseline sunmap.r3 daily potential at the CLI latitude.

Decision

For observed-Daymet climate publication, WEPPpy will normalize only genuine over-TOA daily radiation rows before writing generated WEPP CLI radiation:

  • compute the baseline sunmap.r3 horizontal daily potential in Langleys/day from day-of-year and CLI latitude using the legacy sunmap formula and solar constant 1.94 Ly min^-1;
  • when Daymet-derived srad(l/day) exceeds that bound, publish the largest CLIGEN/WEPP CLI rad value that remains less than or equal to the bound;
  • also apply that publication-safe value when a fractional source value is at or below sunmap.r3 but the integer CLI rad formatter would round it above sunmap.r3;
  • leave all non-over-bound rows unchanged;
  • preserve the acquisition Daymet parquet unchanged; keep normalization provenance in the separate CSV rather than rewriting source columns;
  • write a daymet_radiation_toa_normalization_<label>.csv artifact listing affected dates, original values, computed bounds, normalized values, excess, latitude, and reason.

This rule applies to the observed-Daymet single-location and interpolated producer helpers that write Daymet radiation into generated CLI rad.

Decision Provenance (Required for Parameterization Changes)

Decision Venue: Codex user request thread, 2026-06-06 20:55 UTC Participants Present: User, Codex Decision Owner(s): User / WEPPcloud operator request Implementer(s): Codex

Change Summary

Old behavior:

  • observed-Daymet srad(l/day) was copied into CLI rad without checking against the baseline daily radiation potential;
  • over-TOA Daymet rows reached downstream openWEPP and failed there with CLIM-RUNTIME-E-017.

New behavior:

  • observed-Daymet srad(l/day) is compared to baseline sunmap.r3 using the CLI latitude and day-of-year;
  • rows above sunmap.r3, or rows whose integer CLI publication would exceed sunmap.r3, are bounded to the publication-safe integer value below sunmap.r3;
  • working-DataFrame provenance columns and CSV artifact preserve the original source value and the exact physical bound plus the publication-safe value used.

Rationale

Daily radiation above top-of-atmosphere horizontal potential is physically invalid for the WEPP CLI boundary. Normalizing at the WEPPpy producer boundary keeps openWEPP fail-closed guards intact while preventing known invalid source rows from blocking downstream validation and operation.

Using baseline sunmap.r3 avoids an arbitrary clamp. It matches the downstream contract that rejected the values, keeps the unit in Langleys/day, and preserves auditability through explicit artifacts.

The WEPP CLI rad field is emitted as an integer by ClimateFile.replace_var(). Therefore the production value must be the largest integer-publishable value that does not exceed the exact sunmap.r3 bound; otherwise a normalized fractional bound such as 458.706289 can publish as 459 and still trip the downstream guard.

Alternatives Considered

  1. Relax openWEPP's radiation guard - Rejected. The guard encodes the downstream physical invariant and should remain fail-closed.
  2. Treat genuine over-TOA Daymet values as an external-source HOLD - Rejected. The source defect is normalizable to a physical upper bound at the WEPPpy producer boundary with clear provenance.
  3. Fail closed before CLI publication - Rejected for this source class because bounded normalization preserves operational observed-Daymet workflows while retaining evidence.
  4. Clamp to a fixed numeric threshold - Rejected. The physically valid maximum depends on day-of-year and latitude.

Consequences

  • Positive:
    • Observed-Daymet CLI publication no longer emits radiation above the downstream TOA bound.
    • Affected values remain auditable through unchanged source parquet and CSV artifacts.
    • openWEPP source-bound guards can remain strict.
  • Risks:
    • Normalized rows alter source climate forcing for affected dates.
    • The bound uses CLI metadata latitude, matching downstream consumption, even though Daymet retrieval may use watershed centroid latitude.
    • Reviewers must distinguish this bounded normalization from silent clipping.

Evidence

  • Work package: docs/work-packages/20260606_indispensable_presenter_daymet_radiation_bounds/package.md
  • Initial evidence: docs/work-packages/20260606_indispensable_presenter_daymet_radiation_bounds/artifacts/initial_radiation_evidence.md
  • Execution evidence: docs/work-packages/20260606_indispensable_presenter_daymet_radiation_bounds/artifacts/execution_evidence.md
  • openWEPP downstream contract evidence: /workdir/openWEPP/docs/specifications/science-contracts/contracts/SC-CLIMATE-001.md#inv-climate-013

Risk and Rollback Notes

Monitor observed-Daymet climate builds for unexpected numbers of normalized rows. If normalization proves too broad or the bound is later revised, rollback is to remove the normalization helper and return to source-value publication, which will again let downstream guards fail closed on over-bound rows.

Implementation Notes

  • Production implementation: wepppy/nodb/core/climate_build_helpers.py
  • Regression coverage: tests/nodb/test_climate_build_helpers.py
  • Normalization artifact naming: daymet_radiation_toa_normalization_<label>.csv
  • Working-DataFrame provenance columns (not persisted over source parquet):
    • srad_source(l/day)
    • srad_toa_bound(l/day)
    • srad_toa_publication_bound(l/day)
    • srad_toa_normalized
    • srad_toa_normalization_reason
    • srad_toa_bound_latitude(deg)

Source preservation amendment (2026-09-17)

Operator explicitly requested that retained Daymet source parquet be read-only for downstream PRN/CLI preparation. The earlier source overwrite exposed in-place PRN unit conversions under incorrect physical-unit labels. Both single and interpolated builders must preserve acquisition artifacts; use the existing normalization CSV for derived values and provenance. Numerical bounds, source radiation handling (including legacy source columns), CLI units and publication rounding are unchanged. Conformance verified by focused tests and real CLIGEN replay. This supersedes the original requirement to persist normalization columns into the source parquet.