Add minor reservoirs to hydrology

CONTRIBUTORS.md

@@ -2,10 +2,12 @@
 
 | GitHub user     | Real Name        | Affiliation | Date       |
 | --------------- | ---------------- | ----------- | ---------- |
-| 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 |
+| yaswant         | Yaswant Pradhan  | Met Office  | 2026-02-11 |
+| doucla          | Douglas Clark    | UKCEH       | 2026-06-22 |
+| james-bruten-mo | James Bruten     | Met Office  | 2025-12-09 |
+| KatieBlackford  | Katie Blackford  | UKCEH       | 2026-08-21 |
 | eleanorgb       | Eleanor Burke    | Met Office  | 2026-08-24 |
 | maggiehendry    | Maggie Hendry    | Met Office  | 2026-08-21 |
 | DanCopsey       | Dan Copsey       | Met Office  | 2026-08-24 |
 | Pierre-siddall  | Pierre Siddall   | Met Office  | 2026-08-26 |
+| doucla          | Douglas Clark    | UKCEH       | 2026-10-07 |

doc/source/namelists/ancillaries.nml.rst

@@ -1093,7 +1093,7 @@ This namelist specifies the options available for initialising irrigated fractio
 
 .. nml:namelist:: JULES_RIVERS_PROPS
 
-This namelist specifies how spatially varying river routing properties including overbank inundation should be set.
+This namelist specifies how spatially varying river routing properties (including overbank inundation and minor reservoirs) should be set.
 
 .. note:: ``read_from_dump`` is not currently implemented for this namelist, meaning that river ancillary variables cannot be read from a dump file. Initial values of river prognostic variables can however be read from a dump file (see :nml:lst:`JULES_INITIAL`).
 
@@ -1455,18 +1455,28 @@ The following table summarises river routing properties required to run RFM or T
 | ``longitude_2d``           | The longitude of each river grid point must be specified. This field is required only if the model        |
 |                            | coordinates are latitude and longitude, i.e. if :nml:mem:`JULES_LATLON::l_coord_latlon` = FALSE.          |
 +----------------------------+-----------------------------------------------------------------------------------------------------------+
-| ``logn_mean``              | Mean of ln(elevation-elev_min) for each grid cell (in units ln(m))                                        |
+| ``logn_mean``              | Mean of ln(elevation-elev_min) for each grid cell (in units ln(m)).                                       |
 |                            |                                                                                                           |
 |                            | This is only used if :nml:mem:`JULES_OVERBANK::overbank_model` = 3.                                       |
 |                            |                                                                                                           |
 |                            | Note that elev_min is DEM minimum, not river/lake bed level (therefore large values close to water        |
 |                            | bodies can occur in floodplain gridcells).                                                                |
 +----------------------------+-----------------------------------------------------------------------------------------------------------+
-| ``logn_stdev``             | Standard deviation of ln(elevation-elev_min) for each grid cell (in units ln(m))                          |
+| ``logn_stdev``             | Standard deviation of ln(elevation-elev_min) for each grid cell (in units ln(m)).                         |
 |                            |                                                                                                           |
 |                            | This is only used if :nml:mem:`JULES_OVERBANK::overbank_model` = 3.                                       |
 |                            |                                                                                                           |
 +----------------------------+-----------------------------------------------------------------------------------------------------------+
+| ``minor_res_capacity_grid``| Storage capacity of minor reservoirs (kg).                                                                |
+|                            |                                                                                                           |
+|                            | This is only used if :nml:mem:`JULES_RIVERS::l_minor_reservoirs` = TRUE.                                  |
+|                            |                                                                                                           |
++----------------------------+-----------------------------------------------------------------------------------------------------------+
+| ``minor_res_frac_grid``    | Catchment area of minor reservoirs as fraction of area of gridbox.                                        |
+|                            |                                                                                                           |
+|                            | This is only used if :nml:mem:`JULES_RIVERS::l_minor_reservoirs` = TRUE.                                  |
+|                            |                                                                                                           |
++----------------------------+-----------------------------------------------------------------------------------------------------------+
 | ``rivers_outflow_number``  | Number assigned to each river mouth and inland basin on the Rivers grid, to identify the river which      |
 |                            | discharges into it.                                                                                       |
 |                            |                                                                                                           |
@@ -1479,7 +1489,7 @@ The following table summarises river routing properties required to run RFM or T
 |                            | via OASIS the river outflow is distributed over the corresponding river outflow points on the ocean grid. |
 |                            | This is to ensure that water is conserved and rivers discharge into the correct ocean grid points.        |
 +----------------------------+-----------------------------------------------------------------------------------------------------------+
-| ``rivers_storage``         | Water storage (kg) on the Rivers grid.                                                                    |
+| ``rivers_storage``         | Water storage (kg) on the rivers grid.                                                                    |
 |                            |                                                                                                           |
 |                            | This is only used if :nml:mem:`JULES_RIVERS::i_river_vn` = 3.                                             |
 |                            |                                                                                                           |

doc/source/namelists/initial_conditions.nml.rst

@@ -402,18 +402,18 @@ The required variables for a particular configuration, along with their 'type' a
 | Required if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE, :nml:mem:`JULES_RIVERS::i_river_vn` = '2' and                                  |
 | :nml:mem:`JULES_INITIAL::dump_file` = TRUE                                                                                           |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
-| ``rfm_surfstore_rp``             | Surface water storage on river routing points (m3)                                      | none    |
+| ``rfm_surfstore_rp``             | Surface water storage on river routing points (m3).                                     | none    |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
-| ``rfm_substore_rp``              | Sub-surface water storage on river routing points (m3)                                  | none    |
+| ``rfm_substore_rp``              | Sub-surface water storage on river routing points (m3).                                 | none    |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
-| ``rfm_flowin_rp``                | Surface flow into a grid box on river routing points (m3)                               | none    |
+| ``rfm_flowin_rp``                | Surface flow into a grid box on river routing points (m3).                              | none    |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
-| ``rfm_bflowin_rp``               | Sub-surface flow into a grid box on river routing points (m3)                           | none    |
+| ``rfm_bflowin_rp``               | Sub-surface flow into a grid box on river routing points (m3).                          | none    |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | Required if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE, :nml:mem:`JULES_RIVERS::i_river_vn` = '1,3' and                                |
 | :nml:mem:`JULES_INITIAL::dump_file` = TRUE                                                                                           |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
-| ``rivers_sto_rp``                | Water storage (kg)                                                                      | none    |
+| ``rivers_sto_rp``                | Water storage (kg).                                                                     | none    |
 |                                  |                                                                                         |         |
 |                                  | **Alternatively**, can be initialised from an ancillary file via                        |         |
 |                                  | :nml:lst:`JULES_RIVERS_PROPS`. It cannot be requested via :nml:lst:`JULES_INITIAL`      |         |
@@ -423,7 +423,12 @@ The required variables for a particular configuration, along with their 'type' a
 | :nml:mem:`JULES_INITIAL::dump_file` = TRUE and :nml:mem:`OASIS_RIVERS::send_fields` or                                               |
 | :nml:mem:`JULES_OUTPUT_PROFILE::var` contains ``outflow_per_river``.                                                                 |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
-| ``rivers_outflow_rp``            | River outflow on river routing points (kg s\ :sup:`-1`)                                 | none    |
+| ``rivers_outflow_rp``            | River outflow on river routing points (kg s\ :sup:`-1`).                                | none    |
++----------------------------------+-----------------------------------------------------------------------------------------+---------+
+| Required if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE, :nml:mem:`JULES_RIVERS::l_minor_reservoirs` = TRUE and                         |
+| :nml:mem:`JULES_INITIAL::dump_file` = TRUE                                                                                           |
++----------------------------------+-----------------------------------------------------------------------------------------+---------+
+| ``minor_res_storage``            | Water stored in minor reservoirs, on river routing points (kg).                         | none    |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | Required if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE, :nml:mem:`JULES_RIVERS::i_river_vn` = '3',                                     |
 | :nml:mem:`JULES_INITIAL::dump_file` = TRUE and :nml:mem:`OASIS_RIVERS::send_fields` contains ``inland_outflow``.                     |
@@ -432,7 +437,7 @@ The required variables for a particular configuration, along with their 'type' a
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | Required if :nml:mem:`JULES_VEGETATION::photo_acclim_model` = 2 or 3                                                                 |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
-| ``t_growth_gb``                  | Running mean air temperature (K)                                                        | none    |
+| ``t_growth_gb``                  | Running mean air temperature (K).                                                       | none    |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
 
 
@@ -444,6 +449,10 @@ The required variables for a particular configuration, along with their 'type' a
   if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE, :nml:mem:`JULES_RIVERS::i_river_vn` = '1,3' and :nml:mem:`JULES_INITIAL::dump_file` = FALSE,
   ``rivers_sto_rp`` is initialised to zero **unless** it is initialised from an ancillary via :nml:lst:`JULES_RIVERS_PROPS`.
 
+.. warning::
+  if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE, :nml:mem:`JULES_RIVERS::l_minor_reservoirs` = TRUE and :nml:mem:`JULES_INITIAL::dump_file` = FALSE,
+    ``minor_res_storage`` is initialised to zero.
+
 .. |mu| unicode:: μ .. u
 
 

doc/source/namelists/jules_rivers.nml.rst

@@ -44,6 +44,21 @@ River routing introduces two more grids to a JULES run: the river routing input
    ``3``
        Use a standalone JULES implementation of the TRIP model (see Oki et al. 1999).
 
+
+.. nml:member:: l_minor_reservoirs
+
+   :type: logical
+   :default: F
+
+   Switch for enabling routing through minor reservoirs. Only used if :nml:mem:`JULES_RIVERS::l_rivers` is TRUE.
+
+   TRUE
+       Surface runoff is routed through minor reservoirs before reaching the river network.
+
+   FALSE
+       No minor reservoirs are modelled.
+
+
 .. nml:member:: l_riv_overbank
 
    :type: logical
@@ -96,7 +111,7 @@ River routing introduces two more grids to a JULES run: the river routing input
       :type: real
       :permitted: > 0
       :default: None
-      :suggested: 0.20 m/s (global), 0.40 m/s (1 km resolution, Bell et al. 2007)
+      :suggested: 0.20 m s\ :sup:`-1` (global), 0.40 m s\ :sup:`-1` (1 km resolution, Bell et al. 2007)
 
       The land wave speed (kinematic wave speed for surface flow in a land grid box on the river routing grid, m s\ :sup:`-1`). This is the speed at which water moves through surface soil in a non-river grid cell (even without major rivers, there are always minor water courses so these cells do still contribute flow to neighbouring cells).
 
@@ -106,7 +121,7 @@ River routing introduces two more grids to a JULES run: the river routing input
       :type: real
       :permitted: > 0
       :default: None
-      :suggested: 0.62 m/s (global), 0.50 m/s (1 km resolution, Bell et al. 2007)
+      :suggested: 0.62 m s\ :sup:`-1` (global), 0.50 m s\ :sup:`-1` (1 km resolution, Bell et al. 2007)
 
       The river wave speed (kinematic wave speed for surface flow in a river grid box on the river routing grid, m s\ :sup:`-1`). This value should be close to the :nml:mem:`rivers_speed` used by TRIP, but not identical because RFM makes different assumptions about e.g. meandering.
 
@@ -116,7 +131,7 @@ River routing introduces two more grids to a JULES run: the river routing input
       :type: real
       :permitted: > 0
       :default: None
-      :suggested: <= :nml:mem:`cland`. 0.10 m/s (global), 0.05 m/s (1 km resolution, Bell et al. 2007)
+      :suggested: <= :nml:mem:`cland`. 0.10 m s\ :sup:`-1` (global), 0.05 m s\ :sup:`-1` (1 km resolution, Bell et al. 2007)
 
       The subsurface land wave speed (kinematic wave speed for subsurface flow in a land grid box on the river routing grid, m s\ :sup:`-1`).
 
@@ -126,7 +141,7 @@ River routing introduces two more grids to a JULES run: the river routing input
       :type: real
       :permitted: > 0
       :default: None
-      :suggested: <= :nml:mem:`criver`. 0.15 m/s (global), 0.05 m/s (1 km resolution, Bell et al. 2007)
+      :suggested: <= :nml:mem:`criver`. 0.15 m s\ :sup:`-1` (global), 0.05 m s\ :sup:`-1` (1 km resolution, Bell et al. 2007)
 
       The subsurface river wave speed (kinematic wave speed for subsurface flow in a river grid box on the river routing grid, m s\ :sup:`-1`).