Skip to content

Document the model rules that extend the published formulation #331

Description

@soaressgabriel

Description

The review of the code against the journal supplement (Water 2022, 14, 1958; equations S1 to S35, PDF pages 5 to 12) found rules the model applies by design that the supplement does not state. The model authors confirmed them as intentional on 2026-09-05. They belong in the model description (doc/source/overview.rst, and equations.rst once the documentation review lands) so that the conformity tests and the users can rely on them:

  1. Root zone water balance (S1, S12): TU_R is bounded below by zero in addition to the documented upper bound TU_sat; a negative balance is closed at zero (Soil.get_actual_soil_moist_cont). Reason: no negative soil water storage.
  2. Root zone in open water cells (S1): when a_o = 1 the root zone is kept saturated, TU_R = TU_sat; the supplement's TU_R = TU_S reading is not the intended coupling of the two layers.
  3. Saturation-excess runoff (S4): when TU_R = TU_sat the surface runoff is P - I instead of C_SR C_h (P - I) (already stated in overview.rst: "When the soil is saturated ..."). Reason: all the effective precipitation runs off a saturated soil.
  4. Open water cells (S13, S28): the open water evapotranspiration is capped at the precipitation, ET_R,W <= P, and the surface runoff floored at zero, SR = max(P - ET_R,W, 0), so a water cell never contributes a negative flow to Q_Tot and to the accumulation.
  5. Impervious area evapotranspiration (S21, S30): ET_R,I is the user-chosen constant i_imp, in the 1 to 3 mm range, not the vegetation interception.
  6. Domain statements: kp > 0 is enforced by the input validation only (no runtime guard); C_wp <= 1 is the physical domain of S5.

Proposed solution

State each rule next to its equation in the overview, with the reason, and carry them into equations.rst during the documentation review; the paper tests cite this issue until then.

Additional context

Findings 4, 8, 9, 10, 11, 13 and 15 of the review (confirmed as intentional or clarified). Findings 1, 2, 3 and 12 became #318, #319, #322 and #320.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationpaperConformity with the published model description

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions