WEPPcloud

← Back to help

ADR-0024: MOFE Configuration Cap of Five OFEs

Status: Accepted Date: 2026-07-21

Context

Multiple-OFE (MOFE) watershed segmentation accepts watershed.mofe_max_ofes. The controller's absent-option fallback and its upper safety bound are both 19, so MOFE configuration files that omit the option can create up to 19 OFEs per hillslope. The project needs a lower, explicit configuration-level cap and a Canada WBT MOFE configuration.

Decision

Set watershed.mofe_max_ofes = 5 in every active MOFE .cfg file. Add canada-wbt-mofe.cfg as the Canada variant of the existing earth/C3S WBT configuration, with wepp.multi_ofe = true, WBT delineation, and the same five-OFE cap. Register it as a preview WBT configuration available to users.

The implementation-level fallback and hard safety ceiling remain 19 for non-MOFE and legacy configurations that do not declare this parameter.

Decision Provenance (Required for Parameterization Changes)

Decision Venue: Codex user session, 2026-07-21 America/Los_Angeles Participants Present: repository user; Codex Decision Owner(s): repository user Implementer(s): Codex

Change Summary

Parameter Previous MOFE configuration behavior New behavior
watershed.mofe_max_ofes Not declared; controller fallback allowed 19 Explicitly 5 in each MOFE configuration
Canada WBT MOFE No selectable MOFE configuration canada-wbt-mofe preview WBT configuration with cap 5

Rationale

An explicit per-configuration value prevents the 19-OFE fallback from silently governing new MOFE runs and keeps segmentation complexity bounded consistently across existing and Canada WBT MOFE setups.

Alternatives Considered

  1. Change the global fallback from 19 to 5 — rejected because that would alter legacy and non-MOFE configurations that do not opt into this parameter.
  2. Change only the CONUS WBT MOFE configuration — rejected because all MOFE configurations need the same explicit limit.
  3. Retain the 19-OFE cap — rejected by the decision owner due to unnecessary segmentation complexity.

Consequences

New runs created with an MOFE configuration will contain no more than five OFE segments per hillslope, subject to the existing lower bound and available-cell limit. Existing persisted runs retain their current saved watershed settings.

Evidence

  • wepppy/nodb/core/watershed.py: absent-option fallback is 19.
  • wepppy/nodb/core/watershed_mixins.py: segmentation applies the configured cap after existing cell-count and safety-bound checks.
  • tests/weppcloud/routes/test_feature_registry_runtime.py: validates every registry-exposed MOFE configuration declares the cap as 5.

Risk and Rollback Notes

The lower cap can reduce spatial segmentation detail for newly created runs. Rollback is to restore the prior configuration value or omission; no migration or generated-run artifact rewrite is required.

Implementation Notes

The runtime safety ceiling remains 19. This ADR changes configuration defaults, not the controller's accepted input range or segmentation algorithm.