Avoid negative saturated-zone storage by limiting baseflow to available water

[LINAMARIAOSORIO]

Checklist

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?
• Added tests for changed code.
• Updated documentation for changed code.

Description

Soil.get_baseflow computed the recession baseflow without checking the water available in the saturated zone, so the balance TU_S = TU_S(t-1) + REC - BF could become negative. The baseflow is now min(BF_calc, TU_S(t-1) + REC), where BF_calc is the recession equation (zero below the threshold).

Follow-up commits on top of the fix:

• Regression tests in tests/unit/hydrological_processes/test_module_soil.py: the limit binds and the balance ends at zero (fails on main); the limit does not bind; below the threshold the baseflow stays zero although water is available.
• ruff format of the changed module; the get_baseflow docstring restored and extended with the limit.
• doc/source/overview.rst, baseflow section: the recession equation keeps its form under the label baseflow-recession and the limit BF = min(BF_calc, TU_{S,T-1} + REC) is the new baseflow equation, with the same TU_{S,T-1} notation as the storage equation tus.
• Merge of fix_320 and a changelog entry under Unreleased › Fixed.

Stacked on #324 (base branch fix_320): the diff of this pull request is rubem/hydrological_processes/_soil.py, the tests, the documentation and the changelog line.

Related Issue

• Resolve Prevent negative saturated-zone storage by limiting baseflow to available water #322

Motivation and context

Mass conservation: a negative saturated-zone storage means the baseflow delivered water that was not in the aquifer. Two points for the scientific review: the limited baseflow becomes BF_{T-1} of the next step, so the recession sequence changes after a limited step; and the regression dataset never triggers the limit (the exact job reports byte-identical outputs with and without it), so the behaviour is covered by the unit tests.

How has this been tested

• Local suite (pytest --ignore=tests/integration/doc): 1001 passed, 1 skipped.
• test_baseflowCalc_capped_by_available_water fails with _soil.py from main (returns 3.995 instead of 2.5) and passes here.
• The docs job (sphinx-build -W) was run locally with act on this branch: green. Golden fixtures are not affected: byte-exact reproduction verified in the golden environment container with this branch.
• CI on this pull request: ci-success green.

Screenshots

• N/A

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.47%. Comparing base (ed3be1c) to head (21001b7).

Additional details and impacted files

@@           Coverage Diff            @@
##           fix_320     #325   +/-   ##
========================================
  Coverage    92.47%   92.47%           
========================================
  Files           60       60           
  Lines         3906     3908    +2     
  Branches       487      487           
========================================
+ Hits          3612     3614    +2     
  Misses         238      238           
  Partials        56       56           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.