Merge branch 'master' into jules-shared_extend

.github/workflows/build_docs.yml

@@ -0,0 +1,30 @@
+# This workflow ensures that required environment is activated, and ensures
+# that the JULES Sphinx documenation builds correctly.
+
+name: build_docs
+
+# Controls when the action will run
+on: 
+    push:
+    pull_request:
+
+    # Enables manual running from the Actions tab
+    workflow_dispatch:
+
+jobs:
+    build-and-deploy:
+      runs-on: ubuntu-latest
+
+      steps:
+        - name: checkout
+          uses: actions/checkout@v4
+
+        - name: Build documentation
+          run: |
+            conda update conda
+            conda env create -f environment.yml  
+            eval "$(conda shell.bash hook)"
+            conda activate jules-user-guide
+            cd user_guide/doc
+            make html
+

user_guide/doc/source/namelists/ancillaries.nml.rst

@@ -1024,6 +1024,7 @@ This namelist specifies how spatially varying river routing properties should be
    *  **Model input grid** - The full JULES input grid specified in :nml:lst:`JULES_INPUT_GRID`.
    *  **Land grid** - The grid that JULES runs on (not rivers) - this is the grid that includes land points. If JULES is using a 1-D grid internally, the land grid is the notional 2D grid across which the points can be scattered.
    *  **River routing input grid** - The grid on which river routing ancillaries are provided.
+   *  **River domain** - That part of the river input grid that is selected for modelling.
 
    Information about the river routing input grid and its relationship to the land grid is specified in this namelist. In all cases river routing is only possible if the land and river grids are regular, in that they have a constant spacing between rows and columns (but see note below about 1D model input grids).
 
@@ -1086,23 +1087,21 @@ This namelist specifies how spatially varying river routing properties should be
       The size of the y dimension of the river routing input grid.
 
 
-.. nml:group:: Members used to describe the land grid
+.. nml:member:: l_find_grid
 
-   .. nml:member:: nx_land_grid
+   :type: logical
+   :default: none
 
-      :type: integer
-      :permitted: >= 1
-      :default: none
+   Switch controlling how characteristics of the land grid and the river domain are determined.
 
-      The size of the x dimension of the 2D land grid. This should be large enough to include all land points that are being modelled.
+   FALSE
+      Use namelist values for the variables :nml:mem:`nx_land_grid`, :nml:mem:`ny_land_grid`, :nml:mem:`x1_land_grid` and :nml:mem:`y1_land_grid` to describe the land grid. This value is required so as to recreate some historical results but necessarily requires that the input values are correct and, for some configurations, has deficencies such as producing a river domain that is larger than required.
 
-   .. nml:member:: ny_land_grid
+   TRUE
+      Calculate details of the land grid from the known coordinates of land points. This also triggers differences in how the river domain is set up, including better treatment of cases in which the resolutions of the land and river grids differ and/or land points (e.g. from a regional domain) straddle the longitudinal edges of a global river input grid (a smaller river domain can be identified).
 
-      :type: integer
-      :permitted: >= 1
-      :default: none
 
-      The size of the y dimension of the 2D land grid. This should be large enough to include all land points that are being modelled.
+.. nml:group:: Members used to describe the land grid
 
    .. nml:member:: land_dx
 
@@ -1120,27 +1119,43 @@ This namelist specifies how spatially varying river routing properties should be
 
       The gridbox size in the y direction of the 2D land grid. The units of this are the same as for the model grid - see :nml:mem:`JULES_LATLON::l_coord_latlon`.
 
-   .. nml:member:: x1_land_grid
+   .. nml:group:: Only used with l_find_grid = FALSE
 
-      :type: real
-      :default: none
+      .. nml:member:: nx_land_grid
 
-      The x coordinate of the "western-most" (i.e. first) column of gridpoints in the land grid. The units of this are the same as for the model grid - see :nml:mem:`JULES_LATLON::l_coord_latlon`.
+         :type: integer
+         :permitted: >= 1
+         :default: none
 
-   .. nml:member:: y1_land_grid
+         The size of the x dimension of the 2D land grid. This should be large enough to include all land points that are being modelled.
 
-      :type: real
-      :default: none
+      .. nml:member:: ny_land_grid
+
+         :type: integer
+         :permitted: >= 1
+         :default: none
 
-      The y coordinate of the "southern-most" (i.e. first) row of gridpoints in the land grid. The units of this are the same as for the model grid - see :nml:mem:`JULES_LATLON::l_coord_latlon`.
+      .. nml:member:: x1_land_grid
 
-   .. note:: Although the values in this section (:nml:mem:`nx_land_grid`, :nml:mem:`ny_land_grid`, :nml:mem:`land_dx`, :nml:mem:`land_dy`,  :nml:mem:`x1_land_grid` and :nml:mem:`y1_land_grid`) describe the land grid, they are also used to calculate the area that will be searched for river points. The area to be searched is the rectangle defined by x=x1_land_grid to x1_land_grid+(nx_land_grid*land_dx), y=y1_land_grid to y1_land_grid+(ny_land_grid*land_dy).
+         :type: real
+         :default: none
+
+         The x coordinate of the "western-most" (i.e. first) column of gridpoints in the land grid. The units of this are the same as for the model grid - see :nml:mem:`JULES_LATLON::l_coord_latlon`.
+
+      .. nml:member:: y1_land_grid
+
+         :type: real
+         :default: none
+
+         The y coordinate of the "southern-most" (i.e. first) row of gridpoints in the land grid. The units of this are the same as for the model grid - see :nml:mem:`JULES_LATLON::l_coord_latlon`.
+
+   .. note:: With :nml:mem:`l_find_grid` = F, although :nml:mem:`nx_land_grid`, :nml:mem:`ny_land_grid`, :nml:mem:`land_dx`, :nml:mem:`land_dy`, :nml:mem:`x1_land_grid` and :nml:mem:`y1_land_grid` describe the land grid, they are also used to calculate the area that will be searched for river points (the river domain). The area to be searched is the rectangle defined by x=x1_land_grid to x1_land_grid+(nx_land_grid*land_dx) and y=y1_land_grid to y1_land_grid+(ny_land_grid*land_dy). With :nml:mem:`l_find_grid` = T the model internally seeks to define a river domain that includes all land gridboxes.
 
 
 .. nml:member:: rivers_regrid
 
    :type: logical
-   :default: T
+   :default: F
 
    Flag indicating if variables on the land grid need to be regridded (interpolated) to the river routing grid. This is currently only possible for grids that are regular in latitude and longituide. We distinguish between regridding (which is used between land and river grids of different resolution, or the same resolution but staggered relative to one another) and remapping (between consistent grids of the same resolution).
 
@@ -1272,6 +1287,16 @@ Grids are considered consistent (and therefore regridding is not required) if th
       This is not used for variables where :nml:mem:`use_file` = TRUE, but a placeholder must still be given in that case.
 
 
+.. nml:group:: Additional ancillaries, which may be required depending on requested options
+ 	
+   .. nml:member:: riv_number_file
+	
+      :type: character
+      :default: ''
+
+      Ancillary file containing river numbers, which assign each river mouth on the Rivers grid, to the river which discharges into it. The river number is used in the calculation of 'outflow_per_river' (River outflow into the ocean for each river; kg s\ :sup:`-1`), when it is requested either as a JULES output (:nml:mem:`JULES_OUTPUT_PROFILE::var`) or as a send field when coupled to OASIS (:nml:mem:`OASIS_RIVERS::send_fields`). The river outflow for each river is calculated as the sum of the river outflows corresponding to that river. When passed to the ocean model 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.
+
+
 .. _list-of-rivers-params:
 
 List of rivers properties

user_guide/doc/source/namelists/contents.rst

@@ -32,6 +32,7 @@ These files have specific names, and JULES expects all these files to exist for
    jules_deposition.nml
    jules_snow.nml
    jules_rivers.nml
+   oasis_rivers.nml
    jules_water_resources.nml
    jules_irrig.nml
    science_fixes.nml
@@ -52,4 +53,3 @@ These files have specific names, and JULES expects all these files to exist for
    prescribed_data.nml
    initial_conditions.nml
    output.nml
-   oasis_rivers.nml

user_guide/doc/source/namelists/initial_conditions.nml.rst

@@ -44,7 +44,7 @@ The values of all prognostic variables must be set at the start of a run. This i
 .. nml:group:: Members used to set up spatially varying properties
 
    .. nml:member:: file
-   
+ 
       :type: character
       :default: None
 
@@ -54,7 +54,7 @@ The values of all prognostic variables must be set at the start of a run. This i
 
       If :nml:mem:`dump_file` = TRUE, this should be a JULES dump file.
 
-      If :nml:mem:`dump_file` = FALSE, this should be a file conforming to the :doc:`JULES input requirements </input/overview>`. This file name may use :doc:`variable name templating </input/file-name-templating>`.    
+      If :nml:mem:`dump_file` = FALSE, this should be a file conforming to the :doc:`JULES input requirements </input/overview>`. This file name may use :doc:`variable name templating </input/file-name-templating>`.
 
 
    .. nml:member:: nvars
@@ -271,17 +271,17 @@ The required variables for a particular configuration, along with their 'type' a
 | ``sthu_irr``                     | Unfrozen soil wetness of each layer as a fraction of saturation in irrigated fraction.  | soil    |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | Required if :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0                                                                                |
-+----------------------------------+-----------------------------------------------------------------------------------------+---------+ 
++----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | ``cropdvi``                      | Development index for each crop pft.                                                    | cpft    |
-+----------------------------------+-----------------------------------------------------------------------------------------+---------+ 
++----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | ``croprootc``                    | Root carbon pool for each crop pft (kg m\ :sup:`-2`).                                   | cpft    |
-+----------------------------------+-----------------------------------------------------------------------------------------+---------+ 
++----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | ``cropharvc``                    | Carbon in 'harvest parts' pool for each crop pft (kg m\ :sup:`-2`) .                    | cpft    |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+ 
 | ``cropreservec``                 | Carbon in stem reserves pool for each crop pft (kg m\ :sup:`-2`).                       | cpft    |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+ 
 | ``croplai``                      | Leaf area index of each crop pft.                                                       | cpft    |
-+----------------------------------+-----------------------------------------------------------------------------------------+---------+ 
++----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | ``cropcanht``                    | Height (m) of each crop pft.                                                            | cpft    |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | Required if :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE                                                                                 |
@@ -294,7 +294,7 @@ The required variables for a particular configuration, along with their 'type' a
 | ``zw``                           | Depth from the surface to the water table (m).                                          | None    |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | Required if :nml:mem:`JULES_SOIL::l_bedrock` = TRUE                                                                                  |
-+----------------------------------+-----------------------------------------------------------------------------------------+---------+ 
++----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | ``tsoil_deep``                   | Temperature of each bedrock layer (K)                                                   | bedrock |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | Required if :nml:mem:`JULES_RADIATION::l_snow_albedo` = TRUE                                                                         |
@@ -412,10 +412,16 @@ The required variables for a particular configuration, along with their 'type' a
 | ``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                                                                                           |         
+| :nml:mem:`JULES_INITIAL::dump_file` = TRUE                                                                                           |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | ``rivers_sto_rp``                | Water storage (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` 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    | 
++----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | Required if :nml:mem:`JULES_VEGETATION::photo_acclim_model` = 2 or 3                                                                 |
 +----------------------------------+-----------------------------------------------------------------------------------------+---------+
 | ``t_growth_gb``                  | Running mean air temperature (K)                                                        | none    |
@@ -426,7 +432,7 @@ 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` = '2' and :nml:mem:`JULES_INITIAL::dump_file` = FALSE,
     rfm_surfstore_rp, rfm_substore_rp, rfm_flowin_rp and rfm_bflowin are initialised to zero.
 
-.. warning:: 
+.. warning::
   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.
 

user_guide/doc/source/namelists/jules_rivers.nml.rst

@@ -179,7 +179,7 @@ River routing introduces two more grids to a JULES run: the river routing input
 
       The ratio of the actual to calculated river lengths in a river routing gridbox. See Oki et al. (1999). Oki & Sud (1998) called this the Meandering Ratio r_M and suggested an average global value of 1.4.
 
-.. nml:group:: TRIP parameters - used if :nml:mem:`i_river_vn` = ``1``
+.. nml:group:: TRIP parameters for UM-TRIP only - i.e. only used if :nml:mem:`i_river_vn` = ``1``
 
    .. nml:member:: lake_water_conserve_method
 
@@ -194,6 +194,18 @@ River routing introduces two more grids to a JULES run: the river routing input
       ``2``
           elake_surft: This is the lake evaporation component of fqw_surft. This avoids the impact that snow melt has on modifying fqw_surft.
 
+   .. nml:member:: trip_globe_shape
+
+      :type: integer
+      :default: 2
+
+      The shape of the Earth in the UM-TRIP river routing scheme.
+
+      ``1``
+          Spherical: Consistent with other component models (e.g. UM and NEMO) and is better at conserving water when passing water between these other models.
+
+      ``2``
+          Ellipsoidal: Closer to the actual shape of the Earth.
 
 .. seealso::
    References:

user_guide/doc/source/namelists/oasis_rivers.nml.rst

@@ -17,15 +17,15 @@ This file contains a single namelists called :nml:lst:`OASIS_RIVERS`, which indi
    :permitted: 2
    :default: imdi
 
-   The number of fields that are received from other models via OASIS coupling. 
+   The number of fields that are received from other models via OASIS coupling.
 
 .. nml:member:: np_send
 
    :type: integer
    :permitted: 0,1
    :default: imdi
 
-   The number of fields that are sent to other models via OASIS coupling. 
+   The number of fields that are sent to other models via OASIS coupling.
 
 .. nml:member:: cpl_freq
 
@@ -40,12 +40,12 @@ This file contains a single namelists called :nml:lst:`OASIS_RIVERS`, which indi
 .. nml:member:: send_fields
 
    :type: character(:)
-   :permitted: 'rflow_outflow'
+   :permitted: 'outflow_per_river'
    :default: ''
 
    List of fields to be sent via coupling from the river executable to other models. Names are case sensitive
 
-.. note::  The only field that can be sent via coupling is the total river runoff (`rflow_outflow`).
+.. note::  The only field that can be sent via coupling is the total river runoff (`outflow_per_river`).
 
 .. nml:member:: receive_fields