Skip to content

32 Add minor reservoirs to hydrology #143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Katie Blackford (KatieBlackford) wants to merge 26 commits into
base: main
Choose a base branch
from
Draft

32 Add minor reservoirs to hydrology #143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
8f86b82
Rose stem fixes for cehwl site (#35)
ppharris Jan 26, 2026
f75c761
rsync-ed with code from my now deleted fork (which was also for branc…
doucla Mar 2, 2026
effec7b
Now including modified files that I forgot to "add" last time round!
doucla Mar 2, 2026
b50bde9
Merge remote-tracking branch 'doucla/vn8.0_minor_reservoirs' into vn8…
KatieBlackford Apr 23, 2026
2429092
Now passing abstraction from minor reservoirs (from water resource co…
doucla May 29, 2026
c1921fe
Net abstraction from rivers is now also passed to rivers as a global …
doucla Jun 8, 2026
63bf14b
Added diagnostics conveyance_loss and river_abstracted.
doucla Jun 12, 2026
dddcc0b
Tidying and clarifying.
doucla Jun 12, 2026
6acd700
Corrected checks around requirements for return flows.
doucla Jun 19, 2026
4fb2bd6
Fix - minor_res_storage can now be read from a dump.
doucla Jun 19, 2026
68db684
Tidying.
doucla Jun 19, 2026
97407c1
Removed git text from metadata, updated macro.
doucla Jun 22, 2026
98b4634
Corrected and added to CONTRIBUTORS.md.
doucla Jun 22, 2026
50bbfee
Correcting another mistake in previous merge.
doucla Jun 22, 2026
a7b192f
Updated user doc to reflect minor reservoirs.
doucla Jun 22, 2026
26e0800
Return flows are now calculated initially assuming the sink is availa…
doucla Jun 26, 2026
eeda4c5
Merge remote-tracking branch 'oldfork/doug_vn8.1_minor_reservoirs' in…
KatieBlackford Jul 15, 2026
403ac46
Fixed error in previous merge
KatieBlackford Jul 15, 2026
77d11a3
Fixed another merge error
KatieBlackford Jul 15, 2026
d5ab1d6
Fixes to run parallel
KatieBlackford Jul 30, 2026
99029d8
fix to ensure minor reservoirs work when dump file called in JULES_in…
Aug 5, 2026
4a30af7
Bug fix for valid ancil data
KatieBlackford Aug 17, 2026
9c68cc1
Fixed metadata error and signed CLA
KatieBlackford Aug 21, 2026
e2e83e2
Removed unused calc_avail_river_water subroutine
KatieBlackford Aug 21, 2026
0997888
Cutting down overly long lines
KatieBlackford Aug 21, 2026
3d0a2b6
Apply suggestions from code review
KatieBlackford Aug 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions CONTRIBUTORS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +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 |
| james-bruten-mo | James Bruten | Met Office | 2025-12-09 |
| ppharris | Phil Harris | UKCEH | 2025-12-18 |
| maggiehendry | Maggie Hendry | Met Office | 2026-01-26 |
| andrewcoughtrie | Andrew Coughtrie | Met Office | 2026-02-10 |
| yaswant | Yaswant Pradhan | Met Office | 2026-02-11 |
| ScottWales | Scott Wales | Bureau of Meteorology | 2026-02-16 |
| t00sa | Sam Clarke-Green | Met Office | 2026-02-27 |
| doucla | Douglas Clark | UKCEH | 2026-06-22 |
| KatieBlackford | Katie Blackford | UKCEH | 2026-08-21 |
18 changes: 14 additions & 4 deletions doc/source/namelists/ancillaries.nml.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 reservirs) 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`).

Expand Down Expand Up @@ -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. |
| | |
Expand All @@ -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. |
| | |
Expand Down
23 changes: 16 additions & 7 deletions doc/source/namelists/initial_conditions.nml.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` | |
Expand All @@ -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``. |
Expand All @@ -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 |
+----------------------------------+-----------------------------------------------------------------------------------------+---------+


Expand All @@ -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


Expand Down
23 changes: 19 additions & 4 deletions doc/source/namelists/jules_rivers.nml.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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).

Expand All @@ -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.

Expand All @@ -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`).

Expand All @@ -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`).

Expand Down
Loading