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:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
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, andequations.rstonce the documentation review lands) so that the conformity tests and the users can rely on them:TU_Ris bounded below by zero in addition to the documented upper boundTU_sat; a negative balance is closed at zero (Soil.get_actual_soil_moist_cont). Reason: no negative soil water storage.a_o = 1the root zone is kept saturated,TU_R = TU_sat; the supplement'sTU_R = TU_Sreading is not the intended coupling of the two layers.TU_R = TU_satthe surface runoff isP - Iinstead ofC_SR C_h (P - I)(already stated inoverview.rst: "When the soil is saturated ..."). Reason: all the effective precipitation runs off a saturated soil.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 toQ_Totand to the accumulation.ET_R,Iis the user-chosen constanti_imp, in the 1 to 3 mm range, not the vegetation interception.kp > 0is enforced by the input validation only (no runtime guard);C_wp <= 1is 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.rstduring the documentation review; thepapertests 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.