New water table depth calculation and full hydraulic connectivity with LSH model - #162
Draft
Nic Gedney (nicgedney) wants to merge 18 commits into
Draft
Nic Gedney (nicgedney) wants to merge 18 commits into
Nic Gedney (nicgedney) wants to merge 18 commits into
Conversation
Nic Gedney (nicgedney)
requested review from
Noah Smith (noahdsmith) and
Sonja (sfolwell)
September 10, 2026 09:20
github-actions
Bot
added
the
cla-required
github-actions
Bot
added
cla-signed
There was a problem hiding this comment.
🟡 Changes recommended
There is a confirmed correctness issue in the new LSH coupling path (wrong soil parameters passed to darcy_ic) and additional high-risk operational/performance concerns in calc_zw2 OpenMP memory usage.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR introduces new hydrology options to (1) calculate water table depth via a new calc_zw2 routine and (2) allow full two-way Darcian hydraulic coupling between the bottom soil layer and the LSH groundwater layer, alongside a broad refactor to wrap many standalone/IMOGEN routines into explicit Fortran modules and update associated Rose metadata and documentation.
Changes:
- Add
l_calc_zw2andl_darcy_lsh_allswitches (code + Rose metadata + docs) and implementcalc_zw2. - Update TOPMODEL soil hydrology to optionally use
calc_zw2and to optionally use a Darcian bottom-boundary flux to the LSH layer. - Refactor multiple standalone + IMOGEN + vegetation routines into modules and update build/workflow/docs collateral accordingly.
File summaries
| File | Description |
|---|---|
| src/util/logging_mod.F90 | Use intrinsic ISO_FORTRAN_ENV import form |
| src/science/vegetation/sow_mod.F90 | Wrap sow in a Fortran module |
| src/science/vegetation/partition_mod.F90 | Wrap partition in a Fortran module |
| src/science/vegetation/emerge_mod.F90 | Wrap emerge in a Fortran module |
| src/science/vegetation/develop_mod.F90 | Wrap develop in a Fortran module |
| src/science/vegetation/crop_mod.F90 | Use new vegetation modules (sow/emerge/develop/partition) |
| src/science/soil/soil_hyd_wt_mod.F90 | Switchable calc_zw vs calc_zw2 call |
| src/science/soil/soil_hyd_jls_mod.F90 | Optional Darcian bottom boundary to LSH layer |
| src/science/soil/calc_zw2_jls_mod.F90 | New calc_zw2 water table depth algorithm |
| src/initialisation/standalone/init_vars_tmp_mod.F90 | Wrap init_vars_tmp in a module |
| src/initialisation/standalone/init_urban_mod.F90 | Wrap init_urban in a module |
| src/initialisation/standalone/init_prescribed_data_mod.F90 | Wrap init_prescribed_data in a module |
| src/initialisation/standalone/init_mod.F90 | Import modularised standalone init routines |
| src/initialisation/standalone/init_irrigation_mod.F90 | Wrap init_irrigation in a module |
| src/initialisation/standalone/init_imogen_mod.F90 | Wrap init_imogen in a module (+ imogen_check use) |
| src/initialisation/standalone/init_fire_mod.F90 | Wrap init_fire in a module |
| src/control/standalone/standalone_control_mod.F90 | Wrap/rename standalone control routine into module |
| src/control/standalone/jules.F90 | Call standalone_control and import IMOGEN update modules |
| src/control/shared/jules_hydrology_mod.F90 | Add l_calc_zw2 / l_darcy_lsh_all + namelist entries |
| src/control/rivers-standalone/rivers_control_mod.F90 | Rename module/subroutine for rivers standalone control |
| src/control/rivers-standalone/river.F90 | Call renamed rivers control routine |
| src/control/imogen/rndm_mod.F90 | Wrap rndm in a module |
| src/control/imogen/response_mod.F90 | Wrap response in a module |
| src/control/imogen/radf_non_co2_mod.F90 | Wrap radf_non_co2 in a module |
| src/control/imogen/radf_co2_mod.F90 | Wrap radf_co2 in a module |
| src/control/imogen/radf_ch4_mod.F90 | Wrap CH4 radiative forcing routines in a module |
| src/control/imogen/pattern_scaling_mod.F90 | Wrap pattern_scaling in a module |
| src/control/imogen/ocean_co2_mod.F90 | Wrap ocean_co2 in a module and use response_mod |
| src/control/imogen/invert_mod.F90 | Wrap invert in a module |
| src/control/imogen/imogen_update_clim_mod.F90 | Wrap imogen_update_clim and add explicit module uses |
| src/control/imogen/imogen_update_carb_mod.F90 | Wrap imogen_update_carb and add explicit module uses |
| src/control/imogen/imogen_check_mod.F90 | Wrap imogen_check in a module |
| src/control/imogen/drdat_mod.F90 | Wrap drdat in a module |
| src/control/imogen/diffcarb_land_co2_mod.F90 | Wrap diffcarb_land_co2 in a module |
| src/control/imogen/diffcarb_land_ch4_mod.F90 | Wrap diffcarb_land_ch4 in a module |
| src/control/imogen/diff_atmos_ch4_mod.F90 | Wrap diff_atmos_ch4 in a module and add explicit END SUBROUTINE |
| src/control/imogen/delta_temp_mod.F90 | Wrap delta_temp in a module and use invert_mod |
| src/control/imogen/day_calc_mod.F90 | Wrap day_calc in a module and use rndm_mod |
| src/control/imogen/clim_calc_mod.F90 | Wrap clim_calc, use day_calc_mod, tighten ainfo intent |
| rose-meta/jules-standalone/versions.py | Add upgrade macro adding new hydrology namelist settings |
| rose-meta/jules-standalone/HEAD/rose-meta.conf | Add metadata for new hydrology switches + triggers |
| rose-meta/jules-fcm-make/versions.py | Add version bump macro vn8.2 → vn8.2_t138 |
| etc/fcm-make/make.cfg | Update standalone build explicit dependency config |
| etc/fcm-make/make-river.cfg | Update rivers build file list to renamed init prescribed data file |
| etc/fcm-make/compiler/cray_12_plus.cfg | Update Cray compile override to renamed init prescribed data file |
| doc/source/namelists/jules_hydrology.nml.rst | Document l_calc_zw2 and l_darcy_lsh_all |
| doc/pyproject.toml | Add project URLs metadata |
| CONTRIBUTORS.md | Add contributor entry |
| .github/zizmor.yml | Add Zizmor workflow linter configuration |
| .github/workflows/user-guide.yaml | Harden/pin actions and adjust deployment gating env usage |
| .github/workflows/umdp3_fixer.yaml | Pin reusable workflow ref and set minimal permissions |
| .github/workflows/trigger-project-workflow.yaml | Harden permissions and pin reusable workflow ref |
| .github/workflows/track-review-project.yaml | Harden permissions and pin reusable workflow ref |
| .github/workflows/cla-check.yaml | Add concurrency, harden permissions, pin reusable workflow ref |
| .github/workflows/check-cr-approved.yaml | Harden permissions and pin reusable workflow ref |
| .github/pull_request_template.md | Template formatting + spelling fixes |
Review details
- Files reviewed: 56/56 changed files
- Comments generated: 7
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+128
to
+132
| wgt(nshyd+1), & | ||
| ! weighting to estimate water table from individual layer estimates | ||
| zw_l(npnts,nshyd+1), & | ||
| ! water table estimate for each layer | ||
| zdepth(0:nshyd+1), & |
Comment on lines
+158
to
+161
| smclu(npnts,nshyd), & | ||
| ! Unfrozen soil moisture contents of each layer (kg/m2). | ||
| dwflux_dsthu2_tmp(npnts,nshyd+1) | ||
| ! The rate of change of the explicit flux with STHU2 (kg/m2/s). |
Comment on lines
+175
to
+176
| FALSE | ||
| Only gravitation drainage is allowed between bottom soil layer and the lsh groundwater layer. |
Comment on lines
+48
to
+52
| class vn82_t1(MacroUpgrade): | ||
|
|
||
| """Upgrade macro from JULES by Author""" | ||
|
|
||
| BEFORE_TAG = "vnY.Y" | ||
| AFTER_TAG = "vnY.Y_txxxx" | ||
| BEFORE_TAG = "vn8.2" |
Comment on lines
+12
to
+14
| ! is inferred from the balance between pressure head | ||
| ! pressure head gradient and gravity, and using the | ||
| ! Newton-Raphson method the water table depth is |
Comment on lines
+16
to
+18
| ! In this routine, instead of using the total column | ||
| ! moisture deficit, the water table is estimated "upto" | ||
| ! each soil layer by considering the soil moisture deficit |
| ksz(:,nshyd), sthu(:,nshyd), & | ||
| w_flux(:,nshyd), dwflux_dsthu1(:,nshyd)) | ||
| IF (l_darcy_lsh_all) THEN | ||
| dz_lsh = zw_max-zdepth(nshyd) |
There was a problem hiding this comment.
Depending on where the water table is in the deep layer (if it is), zw_max might not be the right choice. Fine for now though.
Noah Smith (noahdsmith)
approved these changes
Sep 13, 2026
Noah Smith (noahdsmith)
left a comment
Noah Smith (noahdsmith)
left a comment
There was a problem hiding this comment.
I am happy from a science point of view - the updated water calculation looks good and the code matches the documentation. Having the two-way connection with the bottom layer makes sense, though strictly delta z should depend on the profile of moisture in the deep layer.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Summary
<-- New water table depth calculation and full hydraulic connectivity with LSH model- #162 -->
Sci/Tech Reviewer: <-- Noah Smith (@noahdsmith) -->
Code Reviewer:
<-- See #138 -->
<-- Brief summary: New code allows for improvements to the LSH model (l_top): calculation of water table depth (l_calc_zw2) and allowing Darcian fluxes between bottom soil layer and the lsh groundwater layer (l_darcy_lsh_all).
(NB the LSH scheme may need re-calibrating for fexp and zw_max values to ensure simulated river flow changes are not detrimental). -->
<-- List any linked PRs here
None
-->
<-- List any blocking PRs or issues to be closed here
None
-->
Code Quality Checklist
(Some checks are automatically carried out via the CI pipeline)
rose-meta/jules-sharedthen have you supplied a linked UM and LFRic Apps PR?Testing
<-- Other testing performed:
rose-stem test also applied to the test branch test_separate_irrigated_bare_soil_evap
individual point comparison with new switches=T compared with stable .
See the issue for more details. -->
trac.log
<--
Development branch:
Test Suite Results - jules - vn8.2_lsh_new_zw_lsh_full_hydraulic_connect/run1
Suite Information
Task Information
✅ succeeded tasks - 676
Test branch:
Test Suite Results - jules - vn8.2_test2_lsh_new_zw_lsh_full_hydraulic_connect/run1
Suite Information
Task Information
✅ succeeded tasks - 676
-->
Security Considerations
Performance Impact
AI Assistance and Attribution
Documentation
Approvals
Please request all relevant approvals. See the CodeOwners.txt file for section owners.
Technical
Scientific
Sci/Tech Review
Please alert the code reviewer via a tag when you have approved the SR
Code Review