New water table depth calculation and full hydraulic connectivity with LSH model

.github/pull_request_template.md

@@ -1,5 +1,7 @@
 # PR Summary
 
+<!-- Oneline Summary -->
+
 Sci/Tech Reviewer: <!-- SR id, filled by author when ready for review (e.g. @octocat) -->
 Code Reviewer: <!-- CR id, filled by SSD -->
 
@@ -26,20 +28,16 @@ Code Reviewer: <!-- CR id, filled by SSD -->
 
 - [ ] I have performed a self-review of my own code
 - [ ] My code follows the project's style guidelines
-- [ ] Comments have been included that aid undertanding and enhance the
-      readability of the code
+- [ ] Comments have been included that aid understanding and enhance the readability of the code
 - [ ] My changes generate no new warnings
 - [ ] If editing `rose-meta/jules-shared` then have you supplied a linked UM and LFRic Apps PR?
 
 ## Testing
 
 - [ ] I have tested this change locally, using the JULES rose-stem suite
-- [ ] If shared files have been modified, I have run the UM and LFRic Apps rose
-      stem suites
-- [ ] If any tests fail (rose-stem or CI) the reason is understood and
-      acceptable (eg. kgo changes)
-- [ ] I have added tests to cover new functionality as appropriate (eg. system
-      tests, unit tests, etc.)
+- [ ] If shared files have been modified, I have run the UM and LFRic Apps rose stem suites
+- [ ] If any tests fail (rose-stem or CI) the reason is understood and acceptable (eg. kgo changes)
+- [ ] I have added tests to cover new functionality as appropriate (eg. system tests, unit tests, etc.)
 
 <!-- Describe other testing performed (if applicable) -->
 
@@ -55,28 +53,21 @@ Code Reviewer: <!-- CR id, filled by SSD -->
 
 ## Performance Impact
 
-- [ ] Performance of the code has been considered and, if applicable, suitable
-      performance measurements have been conducted
+- [ ] Performance of the code has been considered and, if applicable, suitable performance measurements have been conducted
 
 ## AI Assistance and Attribution
 
-- [ ] Some of the content of this change has been produced with the assistance
-      of _Generative AI tool name_ (e.g., Met Office Github Copilot Enterprise,
-      Github Copilot Personal, ChatGPT GPT-4, etc) and I have followed the
-      [Simulation Systems AI policy](https://metoffice.github.io/simulation-systems/FurtherDetails/ai.html)
-      (including attribution labels)
+- [ ] Some of the content of this change has been produced with the assistance of _Generative AI tool name_ (e.g., Met Office Github Copilot Enterprise, Github Copilot Personal, ChatGPT GPT-4, etc) and I have followed the [Simulation Systems AI policy](https://metoffice.github.io/simulation-systems/FurtherDetails/ai.html) (including attribution labels)
 
 <!-- If AI has been used, please provide more details here -->
 
 ## Documentation
 
-- [ ] Where appropriate I have updated documentation related to this change and
-      confirmed that it builds correctly
+- [ ] Where appropriate I have updated documentation related to this change and confirmed that it builds correctly
 
 ## Approvals
 
-Please request all relevant approvals. See the CodeOwners.txt file for section
-owners.
+Please request all relevant approvals. See the CodeOwners.txt file for section owners.
 
 ### Technical
 
@@ -93,7 +84,7 @@ owners.
 - [ ] Hydrology
 - [ ] Vegetation
 - [ ] Veg3 RED Demography
-- [ ] Biogechemistry
+- [ ] Biogeochemistry
 - [ ] Biogenic fluxes
 - [ ] Fire
 - [ ] Lakes

.github/workflows/check-cr-approved.yaml

@@ -1,11 +1,20 @@
+# -----------------------------------------------------------------------------
+# (C) Crown copyright Met Office. All rights reserved.
+# The file LICENCE, distributed with this code, contains details of the terms
+# under which the code may be used.
+# -----------------------------------------------------------------------------
+
 name: Check CR approved
 
 on:
-    pull_request_review:
-        types: [submitted, edited, dismissed]
-    workflow_dispatch:
+  pull_request_review:
+    types: [submitted, edited, dismissed]
+  workflow_dispatch:
 
 jobs:
-    check_cr_approved:
-        if: ${{ github.event.pull_request.number }}
-        uses: MetOffice/growss/.github/workflows/check-cr-approved.yaml@main
+  check_cr_approved:
+    permissions:
+      contents: read  # Required to evaluate the event trigger metadata safely
+      pull-requests: read  # Required to read pull request details
+    if: ${{ github.event.pull_request.number }}
+    uses: MetOffice/growss/.github/workflows/check-cr-approved.yaml@0f9ffe6a138ae9943053621916a850a075997db8 # v1.0.0

.github/workflows/cla-check.yaml

@@ -1,10 +1,29 @@
+# -----------------------------------------------------------------------------
+# (C) Crown copyright Met Office. All rights reserved.
+# The file LICENCE, distributed with this code, contains details of the terms
+# under which the code may be used.
+# -----------------------------------------------------------------------------
+
+# Check Contributor Licence Agreement
+
 name: Legal
 
 on:
   pull_request_target:
 
+concurrency:
+  # Automatically cancels the workflow run instantly before the
+  # engine can parse empty jobs and generate notification emails
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event.pull_request.head.repo.full_name != 'MetOffice/jules' }}
+
+permissions: {}
+
 jobs:
   cla:
-    uses: MetOffice/growss/.github/workflows/cla-check.yaml@main
+    permissions:
+      contents: read  # Required to evaluate the event trigger metadata safely
+      pull-requests: write  # Required for the downstream engine to post status comments on the PR
+    uses: MetOffice/growss/.github/workflows/cla-check.yaml@0f9ffe6a138ae9943053621916a850a075997db8 # v1.0.0
     with:
       cla-url: 'https://github.com/MetOffice/jules/blob/main/CLA.md'

.github/workflows/track-review-project.yaml

@@ -1,3 +1,9 @@
+# -----------------------------------------------------------------------------
+# (C) Crown copyright Met Office. All rights reserved.
+# The file LICENCE, distributed with this code, contains details of the terms
+# under which the code may be used.
+# -----------------------------------------------------------------------------
+
 name: Track Review Project
 
 on:
@@ -7,11 +13,14 @@ on:
       - completed
 
 permissions:
-  actions: read
-  contents: read
-  pull-requests: write
+  contents: read  # Required to evaluate the event trigger metadata safely
 
 jobs:
   track_review_project:
-    uses: MetOffice/growss/.github/workflows/track-review-project.yaml@main
-    secrets: inherit
+    permissions:
+      actions: read  # Required to check out code or parse files safely
+      contents: read  # Required to read the upstream triggered workflow run artifact status
+      pull-requests: write  # Required for the downstream engine to add comments or update metadata on the PR
+    uses: MetOffice/growss/.github/workflows/track-review-project.yaml@0f9ffe6a138ae9943053621916a850a075997db8 # v1.0.0
+    secrets:
+      PROJECT_ACTION_PAT: ${{ secrets.PROJECT_ACTION_PAT }}

.github/workflows/trigger-project-workflow.yaml

@@ -1,3 +1,9 @@
+# -----------------------------------------------------------------------------
+# (C) Crown copyright Met Office. All rights reserved.
+# The file LICENCE, distributed with this code, contains details of the terms
+# under which the code may be used.
+# -----------------------------------------------------------------------------
+
 name: Trigger Review Project
 
 on:
@@ -7,11 +13,14 @@ on:
   pull_request_review_comment:
 
 permissions:
-  actions: read
-  contents: read
-  pull-requests: write
+  contents: read  # Required to evaluate the event trigger metadata safely
 
 jobs:
   trigger_project_workflow:
-    uses: MetOffice/growss/.github/workflows/trigger-project-workflow.yaml@main
-    secrets: inherit
+    if: github.repository == 'MetOffice/jules'
+
+    permissions:
+      actions: read  # Required to check out code or parse files safely
+      contents: read  # Required to read the upstream triggered workflow run artifact status
+      pull-requests: write  # Required for the downstream engine to add comments or update metadata on the PR
+    uses: MetOffice/growss/.github/workflows/trigger-project-workflow.yaml@0f9ffe6a138ae9943053621916a850a075997db8 # v1.0.0

.github/workflows/umdp3_fixer.yaml

@@ -1,10 +1,18 @@
+# -----------------------------------------------------------------------------
+# (C) Crown copyright Met Office. All rights reserved.
+# The file LICENCE, distributed with this code, contains details of the terms
+# under which the code may be used.
+# -----------------------------------------------------------------------------
+
 name: umdp3 Fixer
 
 on:
-    pull_request:
-        types: [opened, synchronize, reopened]
-    workflow_dispatch:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
 
 jobs:
-    umdp3_fixer:
-        uses: MetOffice/growss/.github/workflows/umdp3_fixer.yaml@main
+  umdp3_fixer:
+    permissions:
+      contents: read
+    uses: MetOffice/growss/.github/workflows/umdp3_fixer.yaml@0f9ffe6a138ae9943053621916a850a075997db8 # v1.0.0

.github/workflows/user-guide.yaml

@@ -42,33 +42,33 @@ jobs:
     steps:
       - name: Check deployment conditions
         id: check-deploy
+        env:
+          GH_REPOSITORY: ${{ github.repository }}
+          GH_REF_NAME: ${{ github.ref_name }}
+          GH_EVENT_NAME: ${{ github.event_name }}
         run: |
-          if [[ "${{ github.repository }}" == "MetOffice/jules" && ("${{ github.ref_name }}" == "main" || "${{ github.ref_name }}" == "stable") && ("${{ github.event_name }}" == "push" || "${{ github.event_name }}" == "merge_group" || "${{ github.event_name }}" == "release" || "${{ github.event_name }}" == "workflow_dispatch") ]]; then
+          if [[ "$GH_REPOSITORY" == "MetOffice/jules" && ("$GH_REF_NAME" == "main" || "$GH_REF_NAME" == "stable") && ("$GH_EVENT_NAME" == "push" || "$GH_EVENT_NAME" == "merge_group" || "$GH_EVENT_NAME" == "release" || "$GH_EVENT_NAME" == "workflow_dispatch") ]]; then
             echo "should-deploy=true" >> $GITHUB_OUTPUT
           else
             echo "should-deploy=false" >> $GITHUB_OUTPUT
           fi
 
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           path: ${{ env.JULES_PATH }}
           # Get all refs to build historic versions
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Setup uv with Python ${{ env.PYTHON_VRSN }}
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           python-version: ${{ env.PYTHON_VRSN }}
-
-      - name: Cache uv venv
-        uses: actions/cache@v4
-        with:
-          path: ${{ env.VENV_PATH }}
-          key: ${{ runner.os }}-uv-${{ env.PYTHON_VRSN }}-${{ hashFiles('doc/pyproject.toml', 'doc/uv.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-uv-${{ env.PYTHON_VRSN }}-
-            ${{ runner.os }}-uv-
+          enable-cache: false
+          cache-dependency-glob: |
+            doc/pyproject.toml
+            doc/uv.lock
 
       - name: Install dependencies
         working-directory: ${{ env.JULES_PATH }}/doc
@@ -119,11 +119,11 @@ jobs:
       # -- Deploy to GitHub Pages only on push to upstream main
       - name: Setup GitHub Pages
         if: steps.check-deploy.outputs.should-deploy == 'true'
-        uses: actions/configure-pages@v5
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d  # v6.0.0
 
       - name: Upload artifact to GitHub Pages
         if: steps.check-deploy.outputs.should-deploy == 'true'
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5.0.0
         with:
           name: github-pages
           path: ${{ env.OUTPUT_PATH }}
@@ -133,4 +133,4 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         if: steps.check-deploy.outputs.should-deploy == 'true'
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128  # v5.0.0

.github/zizmor.yml

@@ -0,0 +1,15 @@
+# ------------------------------------------------------------------------------
+# (c) Crown copyright Met Office. All rights reserved.
+# The file LICENCE, distributed with this code, contains details of the terms
+# under which the code may be used.
+# ------------------------------------------------------------------------------
+
+# Rules for Zizmor GitHub workflow linter. This file is used to configure which
+# rules to ignore for specific workflow files, allowing for exceptions to be
+# made where necessary while still enforcing best practices across the codebase.
+rules:
+  dangerous-triggers:
+    ignore:
+      - "cla-check.yaml"
+      - "track-review-project.yaml"
+      - "trigger-project-workflow.yaml"

CONTRIBUTORS.md

@@ -5,3 +5,4 @@
 | yaswant         | Yaswant Pradhan  | Met Office  | 2026-06-30 |
 | doucla          | Douglas Clark    | UKCEH       | 2026-07-03 |
 | james-bruten-mo | James Bruten     | Met Office  | 2026-07-09 |
+| nicgedney       | Nic Gedney       | Met Office  | 2026-09-10 |

doc/pyproject.toml

@@ -9,5 +9,11 @@ dependencies = [
     "sphinx==8.2.3",
     "sphinx-lint==1.0.1",
 ]
+
+[project.urls]
+repository = "https://github.com/MetOffice/jules"
+documentation = "https://metoffice.github.io/jules/"
+discussion = "https://github.com/MetOffice/simulation-systems/discussions/categories/jules"
+
 [tool.setuptools]
 packages = []

doc/source/namelists/jules_hydrology.nml.rst

@@ -163,6 +163,33 @@ This file sets the hydrology options. It contains one namelist called :nml:lst:`
 
    FALSE
        Use standard wetland and surface saturation fraction calculations.
+   |
+   .. nml:member:: l_darcy_lsh_all
+
+      :type: logical
+      :default: F
+
+   TRUE
+      Enable Darcian fluxes between bottom soil layer and lsh groundwater layer.
+
+   FALSE
+      Only gravitation drainage is allowed between bottom soil layer and the lsh groundwater layer.
+   |
+   .. nml:member:: l_calc_zw2
+
+      :type: logical
+      :default: F
+
+   TRUE
+      Water table depth calculation adapted to reduce impact of root zone abstraction on its over-estimation.
+   FALSE
+      Use standard calculation of water table depth based on Koster et al 2000 which assumes that the soil moisture profile above the water table is determined from the balance between pressure head gradient and gravity.
+
+   .. seealso::
+      References:
+
+      * Koster, R. D. (2000), A catchment-based approach to modeling land surface processes in a general circulation model 1. Model structure J. Geophys. Res. VOL. 105, NO. D20, PAGES 24,809-24,822
+
 
 
 .. nml:group:: Only used if :nml:mem:`JULES_HYDROLOGY::l_pdm` = TRUE

etc/fcm-make/compiler/cray_12_plus.cfg

@@ -60,4 +60,4 @@ $SOURCE_PATH_PREFIX{?} = jules
 build.prop{fc.flags}[$SOURCE_PATH_PREFIX/src/io/model_interface/model_interface_mod.F90] = -O0 -Ovector0 -hfp0 -hflex_mp=strict -hipa0
 #
 # File override to circumvent compiler bug - compiler version: cce/12.0.1
-build.prop{fc.flags}[$SOURCE_PATH_PREFIX/src/initialisation/standalone/init_prescribed_data.F90] = $fflags_common -O1
+build.prop{fc.flags}[$SOURCE_PATH_PREFIX/src/initialisation/standalone/init_prescribed_data_mod.F90] = $fflags_common -O1

etc/fcm-make/make-river.cfg

@@ -89,7 +89,7 @@ extract.path-incl[river] = $extract_path_incl \
 			   src/initialisation/standalone/init_output_mod.F90 \
 			   src/initialisation/standalone/init_rivers.F90 \
 			   src/initialisation/standalone/init_initial_mod.F90 \
-			   src/initialisation/standalone/init_prescribed_data.F90 \
+			   src/initialisation/standalone/init_prescribed_data_mod.F90 \
 			   src/io/dump \
 			   src/io/file_handling \
 			   src/io/input/fill_variables_from_file_mod.F90 \

etc/fcm-make/make.cfg

@@ -65,11 +65,7 @@ preprocess.prop{file-ext.h} = .inc
 build.target = rose-run jules.exe
 
 # Explicit dependencies that need to be defined
-build.prop{ns-dep.o}[jules/src/control/standalone/jules.F90] = jules/src/initialisation/standalone \
-                                                               jules/src/science                   \
-                                                               jules/src/control/imogen            \
-                                                               jules/utils
-build.prop{dep.o}[jules/src/control/standalone/jules.F90] = control.o
+build.prop{ns-dep.o}[jules/src/control/standalone/jules.F90] = jules/utils
 
 
 ################################################################################

rose-meta/jules-fcm-make/versions.py

@@ -516,3 +516,13 @@ class vn81_vn82(MacroUpgrade):
     def upgrade(self, config, meta_config=None):
         # Nothing to do
         return config, self.reports
+
+class vn82_vn82_t138(MacroUpgrade):
+    """Version bump macro"""
+
+    BEFORE_TAG = "vn8.2"
+    AFTER_TAG = "vn8.2_t138"
+
+    def upgrade(self, config, meta_config=None):
+        # Nothing to do
+        return config, self.reports