From 4ef506c1e71645e69ffb1679f89d123742e80c7b Mon Sep 17 00:00:00 2001 From: Lianne Parkhouse Date: Tue, 9 Jan 2024 19:39:41 +0000 Subject: [PATCH 01/24] #32: updating docs to reflect change in trac ticket #1361 --- .../doc/source/namelists/ancillaries.nml.rst | 12 +++++++++- user_guide/doc/source/namelists/contents.rst | 2 +- .../namelists/initial_conditions.nml.rst | 24 ++++++++++++------- .../doc/source/namelists/oasis_rivers.nml.rst | 8 +++---- user_guide/doc/source/output-variables.rst | 9 +++++++ 5 files changed, 40 insertions(+), 15 deletions(-) diff --git a/user_guide/doc/source/namelists/ancillaries.nml.rst b/user_guide/doc/source/namelists/ancillaries.nml.rst index a8c5d70c..2854a265 100644 --- a/user_guide/doc/source/namelists/ancillaries.nml.rst +++ b/user_guide/doc/source/namelists/ancillaries.nml.rst @@ -1140,7 +1140,7 @@ This namelist specifies how spatially varying river routing properties should be .. 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 +1272,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 diff --git a/user_guide/doc/source/namelists/contents.rst b/user_guide/doc/source/namelists/contents.rst index a57b0ef9..5c83d796 100644 --- a/user_guide/doc/source/namelists/contents.rst +++ b/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 diff --git a/user_guide/doc/source/namelists/initial_conditions.nml.rst b/user_guide/doc/source/namelists/initial_conditions.nml.rst index c7f64a95..50c45b87 100644 --- a/user_guide/doc/source/namelists/initial_conditions.nml.rst +++ b/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 `. This file name may use :doc:`variable name templating `. + If :nml:mem:`dump_file` = FALSE, this should be a file conforming to the :doc:`JULES input requirements `. This file name may use :doc:`variable 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. diff --git a/user_guide/doc/source/namelists/oasis_rivers.nml.rst b/user_guide/doc/source/namelists/oasis_rivers.nml.rst index 6d871fea..9748ea72 100644 --- a/user_guide/doc/source/namelists/oasis_rivers.nml.rst +++ b/user_guide/doc/source/namelists/oasis_rivers.nml.rst @@ -17,7 +17,7 @@ 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 @@ -25,7 +25,7 @@ This file contains a single namelists called :nml:lst:`OASIS_RIVERS`, which indi :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 diff --git a/user_guide/doc/source/output-variables.rst b/user_guide/doc/source/output-variables.rst index 84276d7e..a52b9477 100644 --- a/user_guide/doc/source/output-variables.rst +++ b/user_guide/doc/source/output-variables.rst @@ -425,6 +425,15 @@ Rivers | ``rflow_rp`` | River routing gridbox river flow rate (kg m\ :sup:`-2` s\ :sup:`-1`). | np_rivers | | | Only available if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE. | | +-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``rivers_outflow_rp`` | River outflow on river routing grid (kg s\ :sup:`-1`). | np_rivers | +| | Only available if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``outflow_per_river`` | River outflow into the ocean for each river (kg s\ :sup:`-1`). | np_rivers | +| | Only available if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE. | | +| | | | +| | This technically has dimensions of "np_rivers", although only ``[1:n_rivers]``, defined by | | +| | the :nml:mem:`JULES_RIVERS_PROPS::riv_number_file`, is populated. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ | ``rrun_rp`` | River routing gridbox runoff rate received by river routing routine | np_rivers | | | (kg m\ :sup:`-2` s\ :sup:`-1`). | | | | Only available if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE. | | From 1429318fbe2194d5e17f41eefe047bfe04cae01a Mon Sep 17 00:00:00 2001 From: eleanorgb Date: Tue, 16 Jan 2024 14:47:11 +0000 Subject: [PATCH 02/24] changes for vn7.4_imogen_nc jules branch --- .../doc/source/namelists/imogen.nml.rst | 35 +++++-------------- .../doc/source/namelists/model_grid.nml.rst | 10 ++++-- 2 files changed, 16 insertions(+), 29 deletions(-) diff --git a/user_guide/doc/source/namelists/imogen.nml.rst b/user_guide/doc/source/namelists/imogen.nml.rst index 012045a3..d774db44 100644 --- a/user_guide/doc/source/namelists/imogen.nml.rst +++ b/user_guide/doc/source/namelists/imogen.nml.rst @@ -6,11 +6,9 @@ This file contains three namelists called :nml:lst:`IMOGEN_ONOFF_SWITCH`, :nml:l Since IMOGEN calculates the forcing for an entire year at once, an IMOGEN run must have a start time of 00:00:00 on the 1st of January for some year. -IMOGEN is currently restricted to run only on the HadCM3LC grid, i.e. there are 96 x 56 grid cells where each cell has size 3.75 degrees longitude by 2.5 degrees latitude with no Antarctica. This means that: +IMOGEN uses the netcdf read functions in JULES to load the driving data. It also needs grid-area read in as an ancillary. -* :nml:mem:`JULES_INPUT_GRID::nx` = 96 and :nml:mem:`JULES_INPUT_GRID::ny` = 56. - -IMOGEN also uses its own I/O, so it expects IMOGEN specific files in a different format to JULES - this may change in the future. Examples of IMOGEN input files can be found in the data provided to run the 'rose stem' test suites on supported platforms (e.g. JASMIN). +IMOGEN still reads the 1d data from ascii files within the code - this will change in the future. .. seealso:: References: @@ -49,7 +47,7 @@ IMOGEN also uses its own I/O, so it expects IMOGEN specific files in a different Switch for IMOGEN. TRUE - IMOGEN is used to generate meteorological forcing data. + IMOGEN is used to generate meteorological forcing data and drive JULES. FALSE No effect. @@ -276,14 +274,6 @@ IMOGEN also uses its own I/O, so it expects IMOGEN specific files in a different Number of years of emission data in file. -.. nml:member:: file_points_order - - :type: character - :default: None - - File containing the mapping of IMOGEN global grid points onto IMOGEN land points (different from the JULES land points). - - .. nml:member:: initialise_from_dump :type: logical @@ -380,35 +370,28 @@ IMOGEN also uses its own I/O, so it expects IMOGEN specific files in a different Initial ocean temperature (K). -.. nml:member:: dir_patt +.. nml:member:: file_patt :type: character :default: None - Directory containing the patterns. - - Files in this directory are expected to be in a specific format - see the IMOGEN example. + Netcdf file containing the patterns. It should be monthly data (12 months total) with the dimension 'imogen_drive' representing time. -.. nml:member:: dir_clim +.. nml:member:: file_clim :type: character :default: None - Directory containing initialising climatology. - - Files in this directory are expected to be in a specific format - see the IMOGEN example. + Netcdf file containing initialising climatology. It should be monthly data (12 months total) with the dimension 'imogen_drive' representing time. -.. nml:member:: dir_anom +.. nml:member:: file_base_anom :type: character :default: None - Directory containing prescribed anomalies. - - Files in this directory are expected to be in a specific format - see the IMOGEN example. - + Netcdf files containing prescribed anomalies. There should be one for each year and should be in the form 'file_base_anom' followed by 'year' (4 digits) and '.nc' diff --git a/user_guide/doc/source/namelists/model_grid.nml.rst b/user_guide/doc/source/namelists/model_grid.nml.rst index 06185176..064b8d10 100644 --- a/user_guide/doc/source/namelists/model_grid.nml.rst +++ b/user_guide/doc/source/namelists/model_grid.nml.rst @@ -367,11 +367,12 @@ The following table summarises ancillary fields that give the location and relat | | This is only required if :nml:mem:`l_coord_latlon` = FALSE. | | | Note that these can have any valid unit. | +----------------------------+------------------------------------------------------------------------------------------+ -| ``grid_area`` | The area of each gridbox (m\ :sup`2`) | -| | This is only requred if irrigation is being modelled with | +| ``grid_area`` | The area of each gridbox (m\ :sup`2`). | +| | This is requred if irrigation is being modelled with | | | :nml:mem:`JULES_WATER_RESOURCES::l_water_resources` = TRUE and | | | :nml:mem:`JULES_WATER_RESOURCES::l_water_irrigation` = TRUE. | -| | | +| | It is also required when using IMOGEN: | +| | :nml:mem:`IMOGEN_ONOFF_SWITCH::l_imogen` = TRUE | +----------------------------+------------------------------------------------------------------------------------------+ Examples of how to specify the model domain using through this namelist are provided at the end of this section. @@ -387,6 +388,9 @@ Land fraction is the fraction of each gridbox that is land. Currently, JULES con .. warning:: When the input grid consists of a single location (1D and :nml:mem:`JULES_INPUT_GRID::npoints` = 1 or 2D and :nml:mem:`JULES_INPUT_GRID::nx` = :nml:mem:`JULES_INPUT_GRID::ny` = 1), that single location is assumed to be 100% land. + IMOGEN also currently assumes 100% land for each land grid cell. + + For any input grid with more than a single location, the following are used: From 4fcb047a63c65ec54ed927f1fde423332190dfcc Mon Sep 17 00:00:00 2001 From: DanCopsey Date: Tue, 16 Jan 2024 17:14:51 +0000 Subject: [PATCH 03/24] Add trip_globe_shape to namelist --- user_guide/doc/source/namelists/jules_rivers.nml.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/user_guide/doc/source/namelists/jules_rivers.nml.rst b/user_guide/doc/source/namelists/jules_rivers.nml.rst index da751c5b..c4bb8988 100644 --- a/user_guide/doc/source/namelists/jules_rivers.nml.rst +++ b/user_guide/doc/source/namelists/jules_rivers.nml.rst @@ -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 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: From 485de43c6349b49f762f7b37a0d62c301da5e309 Mon Sep 17 00:00:00 2001 From: eleanorgb Date: Mon, 22 Jan 2024 11:02:43 +0000 Subject: [PATCH 04/24] ticket 1265 more changes to docs --- user_guide/doc/source/namelists/imogen.nml.rst | 4 ++-- user_guide/doc/source/output-variables.rst | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/user_guide/doc/source/namelists/imogen.nml.rst b/user_guide/doc/source/namelists/imogen.nml.rst index d774db44..e19f0e63 100644 --- a/user_guide/doc/source/namelists/imogen.nml.rst +++ b/user_guide/doc/source/namelists/imogen.nml.rst @@ -6,9 +6,9 @@ This file contains three namelists called :nml:lst:`IMOGEN_ONOFF_SWITCH`, :nml:l Since IMOGEN calculates the forcing for an entire year at once, an IMOGEN run must have a start time of 00:00:00 on the 1st of January for some year. -IMOGEN uses the netcdf read functions in JULES to load the driving data. It also needs grid-area read in as an ancillary. +IMOGEN uses the netcdf read functions in JULES to load the driving data. It also needs ``grid_area`` read in via :nml:lst:`JULES_LATLON`. -IMOGEN still reads the 1d data from ascii files within the code - this will change in the future. +IMOGEN still reads the 1d data from ascii files within the code - this will change in the near future. .. seealso:: References: diff --git a/user_guide/doc/source/output-variables.rst b/user_guide/doc/source/output-variables.rst index 84276d7e..ff0f7cb1 100644 --- a/user_guide/doc/source/output-variables.rst +++ b/user_guide/doc/source/output-variables.rst @@ -1340,7 +1340,8 @@ Grid and indexing variables | Name | Description | Dimensions | +====================+========================================================================================+============+ | ``grid_area`` | Gridbox surface area (m\ :sup:`2`). | land+sea | -| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_irrigation` = TRUE. | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_irrigation` = TRUE. or | | +| | Only available if :nml:mem:`IMOGEN_ONOFF_SWITCH::l_imogen` = TRUE. | | +--------------------+----------------------------------------------------------------------------------------+------------+ | ``grid_area_rp`` | River routing gridbox surface area (m\ :sup:`2`). | np_rivers | | | Only available if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE. | | From 96c43d63e98971f3820a7a952d404f331c1bbbb7 Mon Sep 17 00:00:00 2001 From: eleanorgb Date: Mon, 22 Jan 2024 11:11:57 +0000 Subject: [PATCH 05/24] driving variables added --- user_guide/doc/source/namelists/imogen.nml.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide/doc/source/namelists/imogen.nml.rst b/user_guide/doc/source/namelists/imogen.nml.rst index e19f0e63..30ac2559 100644 --- a/user_guide/doc/source/namelists/imogen.nml.rst +++ b/user_guide/doc/source/namelists/imogen.nml.rst @@ -6,7 +6,7 @@ This file contains three namelists called :nml:lst:`IMOGEN_ONOFF_SWITCH`, :nml:l Since IMOGEN calculates the forcing for an entire year at once, an IMOGEN run must have a start time of 00:00:00 on the 1st of January for some year. -IMOGEN uses the netcdf read functions in JULES to load the driving data. It also needs ``grid_area`` read in via :nml:lst:`JULES_LATLON`. +IMOGEN uses the netcdf read functions in JULES to load the driving data. The required driving data is specific humidity (kg/kg), precipitaion (kg/m2/s), wind speed (m/s), incoming shortwave radiation (W/m2), incoming longwave radiation (W/m2), air temeprature (K) and diurnal range of air temperature (K). IMOGEN also needs ``grid_area`` read in via :nml:lst:`JULES_LATLON`. IMOGEN still reads the 1d data from ascii files within the code - this will change in the near future. From 23bdb2a38332b68ec9e1930fdc4ddeb087ef1a07 Mon Sep 17 00:00:00 2001 From: DanCopsey Date: Wed, 24 Jan 2024 14:35:56 +0000 Subject: [PATCH 06/24] Change title to be specific to UM-TRIP --- user_guide/doc/source/namelists/jules_rivers.nml.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user_guide/doc/source/namelists/jules_rivers.nml.rst b/user_guide/doc/source/namelists/jules_rivers.nml.rst index c4bb8988..ba2f588e 100644 --- a/user_guide/doc/source/namelists/jules_rivers.nml.rst +++ b/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 @@ -199,7 +199,7 @@ River routing introduces two more grids to a JULES run: the river routing input :type: integer :default: 2 - The shape of the Earth in the TRIP river routing scheme. + 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. From c170a779d0c668f70d5956a52c421200441e191e Mon Sep 17 00:00:00 2001 From: Lianne Parkhouse Date: Thu, 25 Jan 2024 12:15:35 +0000 Subject: [PATCH 07/24] Created build_docs workflow --- .github/workflows/build_docs.yml | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 .github/workflows/build_docs.yml diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml new file mode 100644 index 00000000..779fffc8 --- /dev/null +++ b/.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@v2 + + - 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 + From 18ee620464e9ff9c3756d9ff0f211efb0f69615d Mon Sep 17 00:00:00 2001 From: Lianne Parkhouse Date: Thu, 25 Jan 2024 13:26:33 +0000 Subject: [PATCH 08/24] #36: actions/checkout@v2 is deprecated, updating to v4 instead --- .github/workflows/build_docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index 779fffc8..996d1cec 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -17,7 +17,7 @@ jobs: steps: - name: checkout - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: Build documentation run: | From fd3911f70e42de74e42bae469bfb54e391820f8b Mon Sep 17 00:00:00 2001 From: Giorgia Line <{ID}+{username}@users.noreply.github.com> Date: Thu, 1 Feb 2024 13:25:42 +0000 Subject: [PATCH 09/24] Added new namelist members to pft_params docs --- .../_sources/namelists/pft_params.nml.rst.txt | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/vn7.4/_sources/namelists/pft_params.nml.rst.txt b/vn7.4/_sources/namelists/pft_params.nml.rst.txt index b7858d15..91b09ac2 100644 --- a/vn7.4/_sources/namelists/pft_params.nml.rst.txt +++ b/vn7.4/_sources/namelists/pft_params.nml.rst.txt @@ -337,6 +337,31 @@ ease the direct links to these documents are: Only used with the Medlyn model of stomatal conductance (:nml:mem:`JULES_VEGETATION::stomata_model` = 2). +.. nml:group:: Only used with the SOX (Eller et al. 2020) model of stomatal conductance (:nml:mem:`JULES_VEGETATION::stomata_model` = 3). A value is required for each PFT. + + + .. nml:member:: sox_a_io + + :type: real(npft) + :default: None + + The shape parameter in the xylem vulnerability curve. + + .. nml:member:: sox_p50_io + + :type: real(npft) + :default: None + + Xlem water potential at which xylem hydraulic conductance is half its maximum value (MPa). + + .. nml:member:: sox_rp_min_io + + :type: real(npft) + :default: None + + Plant minimum hydraulic resistance (m2 s MPa/mol). + + .. nml:member:: g_leaf_0_io :type: real(npft) From 6f3eb6fb001ad1f99fd04365e5999b4891ff7573 Mon Sep 17 00:00:00 2001 From: Giorgia Line <{ID}+{username}@users.noreply.github.com> Date: Thu, 1 Feb 2024 13:43:52 +0000 Subject: [PATCH 10/24] Added new stomata model option and reference --- vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt b/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt index 0cb1586f..658e6c18 100644 --- a/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt +++ b/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt @@ -554,6 +554,7 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: Eqn.11 of that paper, and :ref:`Medlyn et al (2012)`. Note that as implemented the model uses a single parameter (g\ :sub:`1`, assuming that g\ :sub:`0` = 0). + 3. The SOX model of :ref:`Eller et al. (2020)` .. warning:: @@ -940,6 +941,10 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: model description – Part 2: Carbon fluxes and vegetation dynamics, Geosci. Model Dev., 4, 701-722, https://doi.org/10.5194/gmd-4-701-2011 +* Eller et al. (2020), Stomatal optimization based on xylem hydraulics + (SOX) improves land surface model simulation of vegetation responses + to climate. New Phytologist 226: + 1622–1637 https://doi.org/10.1111/nph.16419 * Harman, I.N. & Finnigan, J.J. (2007), A simple unified theory for flow in the canopy and roughness sublayer. Boundary-Layer Meteorol. 123: 339. https://doi.org/10.1007/s10546-006-9145-6 From 715f96edd292d00c7d5abbc1429618301f77ed11 Mon Sep 17 00:00:00 2001 From: Giorgia Line <{ID}+{username}@users.noreply.github.com> Date: Thu, 1 Feb 2024 14:14:56 +0000 Subject: [PATCH 11/24] Moved changes to the correct source files --- .../source/namelists/jules_vegetation.nml.rst | 7 +++++- .../doc/source/namelists/pft_params.nml.rst | 25 +++++++++++++++++++ .../namelists/jules_vegetation.nml.rst.txt | 5 ---- .../_sources/namelists/pft_params.nml.rst.txt | 25 ------------------- 4 files changed, 31 insertions(+), 31 deletions(-) diff --git a/user_guide/doc/source/namelists/jules_vegetation.nml.rst b/user_guide/doc/source/namelists/jules_vegetation.nml.rst index 0cb1586f..856073e1 100644 --- a/user_guide/doc/source/namelists/jules_vegetation.nml.rst +++ b/user_guide/doc/source/namelists/jules_vegetation.nml.rst @@ -540,7 +540,7 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: .. nml:member:: stomata_model :type: integer - :permitted: 1 or 2 + :permitted: 1, 2, OR 3 :default: 1 Choice for model of stomatal conductance. @@ -554,6 +554,7 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: Eqn.11 of that paper, and :ref:`Medlyn et al (2012)`. Note that as implemented the model uses a single parameter (g\ :sub:`1`, assuming that g\ :sub:`0` = 0). + 3. The SOX model of :ref:`Eller et al. (2020)` .. warning:: @@ -940,6 +941,10 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: model description – Part 2: Carbon fluxes and vegetation dynamics, Geosci. Model Dev., 4, 701-722, https://doi.org/10.5194/gmd-4-701-2011 +* Eller et al. (2020), Stomatal optimization based on xylem hydraulics + (SOX) improves land surface model simulation of vegetation responses + to climate. New Phytologist 226: + 1622–1637 https://doi.org/10.1111/nph.16419 * Harman, I.N. & Finnigan, J.J. (2007), A simple unified theory for flow in the canopy and roughness sublayer. Boundary-Layer Meteorol. 123: 339. https://doi.org/10.1007/s10546-006-9145-6 diff --git a/user_guide/doc/source/namelists/pft_params.nml.rst b/user_guide/doc/source/namelists/pft_params.nml.rst index b7858d15..91b09ac2 100644 --- a/user_guide/doc/source/namelists/pft_params.nml.rst +++ b/user_guide/doc/source/namelists/pft_params.nml.rst @@ -337,6 +337,31 @@ ease the direct links to these documents are: Only used with the Medlyn model of stomatal conductance (:nml:mem:`JULES_VEGETATION::stomata_model` = 2). +.. nml:group:: Only used with the SOX (Eller et al. 2020) model of stomatal conductance (:nml:mem:`JULES_VEGETATION::stomata_model` = 3). A value is required for each PFT. + + + .. nml:member:: sox_a_io + + :type: real(npft) + :default: None + + The shape parameter in the xylem vulnerability curve. + + .. nml:member:: sox_p50_io + + :type: real(npft) + :default: None + + Xlem water potential at which xylem hydraulic conductance is half its maximum value (MPa). + + .. nml:member:: sox_rp_min_io + + :type: real(npft) + :default: None + + Plant minimum hydraulic resistance (m2 s MPa/mol). + + .. nml:member:: g_leaf_0_io :type: real(npft) diff --git a/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt b/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt index 658e6c18..0cb1586f 100644 --- a/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt +++ b/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt @@ -554,7 +554,6 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: Eqn.11 of that paper, and :ref:`Medlyn et al (2012)`. Note that as implemented the model uses a single parameter (g\ :sub:`1`, assuming that g\ :sub:`0` = 0). - 3. The SOX model of :ref:`Eller et al. (2020)` .. warning:: @@ -941,10 +940,6 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: model description – Part 2: Carbon fluxes and vegetation dynamics, Geosci. Model Dev., 4, 701-722, https://doi.org/10.5194/gmd-4-701-2011 -* Eller et al. (2020), Stomatal optimization based on xylem hydraulics - (SOX) improves land surface model simulation of vegetation responses - to climate. New Phytologist 226: - 1622–1637 https://doi.org/10.1111/nph.16419 * Harman, I.N. & Finnigan, J.J. (2007), A simple unified theory for flow in the canopy and roughness sublayer. Boundary-Layer Meteorol. 123: 339. https://doi.org/10.1007/s10546-006-9145-6 diff --git a/vn7.4/_sources/namelists/pft_params.nml.rst.txt b/vn7.4/_sources/namelists/pft_params.nml.rst.txt index 91b09ac2..b7858d15 100644 --- a/vn7.4/_sources/namelists/pft_params.nml.rst.txt +++ b/vn7.4/_sources/namelists/pft_params.nml.rst.txt @@ -337,31 +337,6 @@ ease the direct links to these documents are: Only used with the Medlyn model of stomatal conductance (:nml:mem:`JULES_VEGETATION::stomata_model` = 2). -.. nml:group:: Only used with the SOX (Eller et al. 2020) model of stomatal conductance (:nml:mem:`JULES_VEGETATION::stomata_model` = 3). A value is required for each PFT. - - - .. nml:member:: sox_a_io - - :type: real(npft) - :default: None - - The shape parameter in the xylem vulnerability curve. - - .. nml:member:: sox_p50_io - - :type: real(npft) - :default: None - - Xlem water potential at which xylem hydraulic conductance is half its maximum value (MPa). - - .. nml:member:: sox_rp_min_io - - :type: real(npft) - :default: None - - Plant minimum hydraulic resistance (m2 s MPa/mol). - - .. nml:member:: g_leaf_0_io :type: real(npft) From c7b01d71081b7699aa9fa9f0cd2d9d1ea831aa1b Mon Sep 17 00:00:00 2001 From: Giorgia Line <{ID}+{username}@users.noreply.github.com> Date: Thu, 1 Feb 2024 13:25:42 +0000 Subject: [PATCH 12/24] Added new namelist members to pft_params docs --- .../_sources/namelists/pft_params.nml.rst.txt | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/vn7.4/_sources/namelists/pft_params.nml.rst.txt b/vn7.4/_sources/namelists/pft_params.nml.rst.txt index b7858d15..91b09ac2 100644 --- a/vn7.4/_sources/namelists/pft_params.nml.rst.txt +++ b/vn7.4/_sources/namelists/pft_params.nml.rst.txt @@ -337,6 +337,31 @@ ease the direct links to these documents are: Only used with the Medlyn model of stomatal conductance (:nml:mem:`JULES_VEGETATION::stomata_model` = 2). +.. nml:group:: Only used with the SOX (Eller et al. 2020) model of stomatal conductance (:nml:mem:`JULES_VEGETATION::stomata_model` = 3). A value is required for each PFT. + + + .. nml:member:: sox_a_io + + :type: real(npft) + :default: None + + The shape parameter in the xylem vulnerability curve. + + .. nml:member:: sox_p50_io + + :type: real(npft) + :default: None + + Xlem water potential at which xylem hydraulic conductance is half its maximum value (MPa). + + .. nml:member:: sox_rp_min_io + + :type: real(npft) + :default: None + + Plant minimum hydraulic resistance (m2 s MPa/mol). + + .. nml:member:: g_leaf_0_io :type: real(npft) From 3f24d565bca32c019bf3c6a8e70e5441348eeec3 Mon Sep 17 00:00:00 2001 From: Giorgia Line <{ID}+{username}@users.noreply.github.com> Date: Thu, 1 Feb 2024 13:43:52 +0000 Subject: [PATCH 13/24] Added new stomata model option and reference --- vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt b/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt index 0cb1586f..658e6c18 100644 --- a/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt +++ b/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt @@ -554,6 +554,7 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: Eqn.11 of that paper, and :ref:`Medlyn et al (2012)`. Note that as implemented the model uses a single parameter (g\ :sub:`1`, assuming that g\ :sub:`0` = 0). + 3. The SOX model of :ref:`Eller et al. (2020)` .. warning:: @@ -940,6 +941,10 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: model description – Part 2: Carbon fluxes and vegetation dynamics, Geosci. Model Dev., 4, 701-722, https://doi.org/10.5194/gmd-4-701-2011 +* Eller et al. (2020), Stomatal optimization based on xylem hydraulics + (SOX) improves land surface model simulation of vegetation responses + to climate. New Phytologist 226: + 1622–1637 https://doi.org/10.1111/nph.16419 * Harman, I.N. & Finnigan, J.J. (2007), A simple unified theory for flow in the canopy and roughness sublayer. Boundary-Layer Meteorol. 123: 339. https://doi.org/10.1007/s10546-006-9145-6 From f0bb81f4fc062265672c248f205d31fbea1d23c2 Mon Sep 17 00:00:00 2001 From: Giorgia Line <{ID}+{username}@users.noreply.github.com> Date: Thu, 1 Feb 2024 16:07:16 +0000 Subject: [PATCH 14/24] Reverting changes to wrong source file --- .../namelists/jules_vegetation.nml.rst.txt | 5 ---- .../_sources/namelists/pft_params.nml.rst.txt | 25 ------------------- 2 files changed, 30 deletions(-) diff --git a/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt b/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt index 658e6c18..0cb1586f 100644 --- a/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt +++ b/vn7.4/_sources/namelists/jules_vegetation.nml.rst.txt @@ -554,7 +554,6 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: Eqn.11 of that paper, and :ref:`Medlyn et al (2012)`. Note that as implemented the model uses a single parameter (g\ :sub:`1`, assuming that g\ :sub:`0` = 0). - 3. The SOX model of :ref:`Eller et al. (2020)` .. warning:: @@ -941,10 +940,6 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: model description – Part 2: Carbon fluxes and vegetation dynamics, Geosci. Model Dev., 4, 701-722, https://doi.org/10.5194/gmd-4-701-2011 -* Eller et al. (2020), Stomatal optimization based on xylem hydraulics - (SOX) improves land surface model simulation of vegetation responses - to climate. New Phytologist 226: - 1622–1637 https://doi.org/10.1111/nph.16419 * Harman, I.N. & Finnigan, J.J. (2007), A simple unified theory for flow in the canopy and roughness sublayer. Boundary-Layer Meteorol. 123: 339. https://doi.org/10.1007/s10546-006-9145-6 diff --git a/vn7.4/_sources/namelists/pft_params.nml.rst.txt b/vn7.4/_sources/namelists/pft_params.nml.rst.txt index 91b09ac2..b7858d15 100644 --- a/vn7.4/_sources/namelists/pft_params.nml.rst.txt +++ b/vn7.4/_sources/namelists/pft_params.nml.rst.txt @@ -337,31 +337,6 @@ ease the direct links to these documents are: Only used with the Medlyn model of stomatal conductance (:nml:mem:`JULES_VEGETATION::stomata_model` = 2). -.. nml:group:: Only used with the SOX (Eller et al. 2020) model of stomatal conductance (:nml:mem:`JULES_VEGETATION::stomata_model` = 3). A value is required for each PFT. - - - .. nml:member:: sox_a_io - - :type: real(npft) - :default: None - - The shape parameter in the xylem vulnerability curve. - - .. nml:member:: sox_p50_io - - :type: real(npft) - :default: None - - Xlem water potential at which xylem hydraulic conductance is half its maximum value (MPa). - - .. nml:member:: sox_rp_min_io - - :type: real(npft) - :default: None - - Plant minimum hydraulic resistance (m2 s MPa/mol). - - .. nml:member:: g_leaf_0_io :type: real(npft) From 45e6c8fba625762d35caa37b3cb0f011b8dc766d Mon Sep 17 00:00:00 2001 From: eleanorgb Date: Mon, 12 Feb 2024 16:57:41 +0000 Subject: [PATCH 15/24] adding more information on the driving data for imogen --- user_guide/doc/source/namelists/imogen.nml.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/user_guide/doc/source/namelists/imogen.nml.rst b/user_guide/doc/source/namelists/imogen.nml.rst index 30ac2559..f1ed3ce6 100644 --- a/user_guide/doc/source/namelists/imogen.nml.rst +++ b/user_guide/doc/source/namelists/imogen.nml.rst @@ -6,7 +6,9 @@ This file contains three namelists called :nml:lst:`IMOGEN_ONOFF_SWITCH`, :nml:l Since IMOGEN calculates the forcing for an entire year at once, an IMOGEN run must have a start time of 00:00:00 on the 1st of January for some year. -IMOGEN uses the netcdf read functions in JULES to load the driving data. The required driving data is specific humidity (kg/kg), precipitaion (kg/m2/s), wind speed (m/s), incoming shortwave radiation (W/m2), incoming longwave radiation (W/m2), air temeprature (K) and diurnal range of air temperature (K). IMOGEN also needs ``grid_area`` read in via :nml:lst:`JULES_LATLON`. +IMOGEN uses the netcdf read functions in JULES to load the driving data. The required driving data is specific humidity (kg/kg), precipitation (kg/m2/s), wind speed (m/s), incoming shortwave radiation (W/m2), incoming longwave radiation (W/m2), air temeprature (K) and diurnal range of air temperature (K). IMOGEN also needs ``grid_area`` read in via :nml:lst:`JULES_LATLON`. + +The meteorological driving data used for IMOGEN are at monthly resolution. IMOGEN requires a monthly climatology and then can use either anomalies from that climatology (:nml:mem:`IMOGEN_RUN_LIST::anlg` set to FALSE and :nml:mem:`IMOGEN_RUN_LIST::anom` set to TRUE) or spatial patterns of changes in each meteorological driving variable per degree of global temperature change (:nml:mem:`IMOGEN_RUN_LIST::anlg` set to TRUE and :nml:mem:`IMOGEN_RUN_LIST::anom` set to TRUE). Patterns can be derived at the required spatial resolution using ESMValTool . IMOGEN still reads the 1d data from ascii files within the code - this will change in the near future. From 97d56e7a90a6b94c329bef91a2af15d0b2990203 Mon Sep 17 00:00:00 2001 From: John M Edwards Date: Wed, 21 Feb 2024 11:47:36 +0000 Subject: [PATCH 16/24] DocSnow_vn7.4 --- .../doc/source/namelists/science_fixes.nml.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/user_guide/doc/source/namelists/science_fixes.nml.rst b/user_guide/doc/source/namelists/science_fixes.nml.rst index 40532594..4a27eb64 100644 --- a/user_guide/doc/source/namelists/science_fixes.nml.rst +++ b/user_guide/doc/source/namelists/science_fixes.nml.rst @@ -99,6 +99,22 @@ is retired. See module for when the switch is due for review. set to zero, which causes the roof to be effectively uncoupled when :nml:mem:`JULES_VEGETATION::l_vegcan_soilfx`. +.. nml:member:: l_fix_neg_snow + + :type: logical + :default: F + + When set to false, the original formulations of melting, interception + and unloading of canopy snow are used. These may result in the generation + of negative snow amounts. Firstly, the original formulation of the + melting of canopy snow is incorrect and excessive melting may be + generated, reducing the mass of snow below 0. This fix corrects this. + Secondly,the interception of snow on an overloaded canopy will, under + the original method of calculation, be negative. With the fix, this is + set to 0 and any snow above the canopy snow capacity is unloaded. + Overloaded canopies may be produced by changess in the snow amounts or + by reductions in the LAI from which the canopy capacity is calculated. + .. nml:member:: l_fix_osa_chloro :type: logical From afc5eb3549f157217a380dcf669520ffe710e3f7 Mon Sep 17 00:00:00 2001 From: doucla Date: Thu, 29 Feb 2024 20:27:12 +0000 Subject: [PATCH 17/24] #40: t1380 init rivers * Documenting new approach - redoing changes that I mysteriously managed to lose previously! * Tweaks from SciTech Review. --------- Co-authored-by: lianneparkhouse <105425887+lianneparkhouse@users.noreply.github.com> --- .../doc/source/namelists/ancillaries.nml.rst | 55 ++++++++++++------- 1 file changed, 35 insertions(+), 20 deletions(-) diff --git a/user_guide/doc/source/namelists/ancillaries.nml.rst b/user_guide/doc/source/namelists/ancillaries.nml.rst index 2854a265..1d1fce77 100644 --- a/user_guide/doc/source/namelists/ancillaries.nml.rst +++ b/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,21 +1119,37 @@ 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 + + .. nml:member:: x1_land_grid + + :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`. + 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:: 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). + .. 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 From d71b3c687fc5805b157c2e0fd5bf365160dbfb6c Mon Sep 17 00:00:00 2001 From: doucla Date: Wed, 10 Apr 2024 11:40:20 +0100 Subject: [PATCH 18/24] T1498 release notes feb24 (#42) * Documenting new approach - redoing changes that I mysteriously managed to lose previously! * Tweaks from SciTech Review. * Included all tickets anticipated. * Belatedly including the JULES7-5 file. --------- Co-authored-by: richardgilham <52403201+richardgilham@users.noreply.github.com> --- .../doc/source/release_notes/JULES7-5.rst | 58 +++++++++++++++++++ .../doc/source/release_notes/contents.rst | 1 + 2 files changed, 59 insertions(+) create mode 100644 user_guide/doc/source/release_notes/JULES7-5.rst diff --git a/user_guide/doc/source/release_notes/JULES7-5.rst b/user_guide/doc/source/release_notes/JULES7-5.rst new file mode 100644 index 00000000..97bb55fd --- /dev/null +++ b/user_guide/doc/source/release_notes/JULES7-5.rst @@ -0,0 +1,58 @@ +JULES version 7.5 Release Notes +=============================== + +The JULES vn7.5 release consists of approximately 17 tickets from 12 authors, including work by many other people. + +Full details of the tickets committed for JULES vn7.5 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #1491. + + +Science changes +------------------------- + + * The stomatal conductance formulation of Eller et al. (2020, doi: 10.1111/nph.16419) is included as an option on the stomatal model switch :nml:mem:`JULES_VEGETATION::stomata_model`. (#1491) + + +General/Technical changes +------------------------- + + * Added water tracers to the hydrology and snow schemes - part of ongoing work to add water tracers/isotopes to JULES. (#1391, 1465) + * For runs with rivers, the new option :nml:mem:`JULES_RIVERS::l_find_grid` can be used to avoid requiring values for variables related to the model grid. This also revises how the area searched for river points is set up. (#1380) + * IMOGEN now reads netcdf files for driving data. (#1265) + * :nml:mem:`JULES_RIVERS::trip_globe_shape` allows the TRIP river routing scheme to consider the Earth as either spherical or ellipsoidal (a more accurate approximation but inconsistent with other component models - e.g. UM and NEMO - which assume the Earth is spherical. Note that this change only affects the UM version of TRIP. (#1374) + * Optimisation and OpenMP efficiency improvements in various places. (#1471) + * Metadata: `jules_snow` and `jules_radiation` LFRic shared items have been migrated to jules-shared, which is also now imported by the UM, and `jules_snow` metadata differences have been consolidated. This is an important step towards having only one source of JULES metadata. Users should experience no difference. JULES developers should refer to the Working Practices. (#1482) + + * ModuleLeaders file renamed for consistency with other projects. (#1452) + + +Bugs fixed +---------- + + * The switch :nml:mem:`JULES_TEMP_FIXES::l_fix_neg_snow` corrects the formulation of snow melting and introduces an extra limit in the calculation of canopy unloading, both of which changes are required to prevent the occurrence of negative snow. Additionally and generically, the snow melt will now be passed through the control code as an increment, not as a rate. This prevents the occurrence of lingering tiny amounts of snow and is required with the fix. (#1396) + * Improved code for water table calculations, accounting for for vertically-varying soil properties. (#1488) + * Bug fix for when `f_wetl is zero` in the layered methane flux code. (#1496) + + +Changes to testing +------------------ + + * Changed initial conditions file for gswp2_es tests. (#1475) + * Added a test (Met Office only) based on how SURF (the Met Office land surface data assimilation system) uses JULES; these namelists follow the global operational GL9 configuration. (#1477) + * Updated the rose-stem suite to be compatible with Cylc8. (#1474) + * Minor changes to NIWA to correct previous errors. (#1487) + * Added a site_validator script, for easier identification of certain errors. (#1483) + * Fixed the parsing of the lfric extract list in suite_report. (#1497) + * Changes for running on the Met Office EXA system. (#1502) + * Introduced SimSys_Scripts checkout. (#1503) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#1498) + + +Documentation can be viewed on the github page ``_. + diff --git a/user_guide/doc/source/release_notes/contents.rst b/user_guide/doc/source/release_notes/contents.rst index a88e2777..f225394a 100644 --- a/user_guide/doc/source/release_notes/contents.rst +++ b/user_guide/doc/source/release_notes/contents.rst @@ -3,6 +3,7 @@ Release notes ============= .. toctree:: + JULES7-5 JULES7-4 JULES7-3 JULES7-2 From 72197e42a98a53d46f1a66fe97ef87a0b70e185a Mon Sep 17 00:00:00 2001 From: eleanorgb Date: Thu, 18 Apr 2024 19:32:58 +0100 Subject: [PATCH 19/24] adding z_burn_max --- .../doc/source/namelists/jules_soil_biogeochem.nml.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/user_guide/doc/source/namelists/jules_soil_biogeochem.nml.rst b/user_guide/doc/source/namelists/jules_soil_biogeochem.nml.rst index 1a860e4e..6968cb2a 100644 --- a/user_guide/doc/source/namelists/jules_soil_biogeochem.nml.rst +++ b/user_guide/doc/source/namelists/jules_soil_biogeochem.nml.rst @@ -206,6 +206,15 @@ If using the ECOSSE soil model, most soil parameters are read from a separate fi Parameter controlling the rate of re-filling of the available inorganic nitrogen pool (1/360 days). This parameter determines how quickly the inorganic nitrogen reaches the roots after the roots uptake from the soil around them. This should be quicker than the turnover rate of inorganic nitrogen. In addition, it has to be small compared with the triffid timestep (360/triffid_period) otherwise the available inorganic nitrogen becomes unstable. Hence the choice of the default value 5. Only used with layered soil carbon and nitrogen scheme (:nml:mem:`l_layeredc` = TRUE and :nml:mem:`JULES_VEGETATION::l_nitrogen` = TRUE). When :nml:mem:`JULES_VEGETATION::l_trif_eq` = TRUE or :nml:mem:`JULES_SOIL_BIOGEOCHEM::diff_n_pft` is greater than (0.5 * 360 / :nml:mem:`JULES_VEGETATION::triffid_period`) then all of the inorganic nitrogen pool is deemed to be available. + + .. nml:member:: z_burn_max + + :type: real + :default: 0.2 + + Parameter controlling the depth to which fire burns soil litter carbon in meters. At depths shallower than this value, the fire can burn soil carbon in the two litter pools (dpm and rpm). If z_burn_max falls within a layer only a proportion of the soil carbon is burnt. Only used with layered soil carbon scheme (:nml:mem:`l_layeredc` = TRUE) and fire (either :nml:mem:`JULES_VEGETATION::l_trif_fire` or :nml:mem:`JULES_VEGETATION::l_inferno` or both). + + .. nml:group:: Parameters for the 4-pool- or ECOSSE-based models (only used if :nml:mem:`soil_bgc_model` = 2 or 3): .. nml:member:: tau_lit From 19dbd37c4eb5e34288aec1a917eb01413a5b520a Mon Sep 17 00:00:00 2001 From: Sam Clarke-Green <74185251+t00sa@users.noreply.github.com> Date: Fri, 26 Apr 2024 10:43:43 +0100 Subject: [PATCH 20/24] Add a deploy step to the workflow (#45) * Add a deploy step to the workflow This adds a script which carries out the actions required to build and release a new version of the jules documentation when the action is a push to the master branch if they do not exist for the most recent release tag. This partitions the workflow to trigger the build-only step when the pushing to a branch or on a PR and only the deployment step when pushing to master. * Address comments from reviewer Remove a holdover from testing from the workflow file, tidy up a comment, and flip the logic used to commit updates to the branch to streamline the code and make the behaviour more obvious. --- .github/scripts/release.py | 207 +++++++++++++++++++++++++++++++ .github/workflows/build_docs.yml | 66 +++++++++- 2 files changed, 267 insertions(+), 6 deletions(-) create mode 100755 .github/scripts/release.py diff --git a/.github/scripts/release.py b/.github/scripts/release.py new file mode 100755 index 00000000..a4e4d536 --- /dev/null +++ b/.github/scripts/release.py @@ -0,0 +1,207 @@ +#!/usr/bin/env python3 + +""" +Automate the steps required to deploy the jules documentation. +""" + +# pylint: disable=useless-return + + +import os +import re +import logging +from argparse import ArgumentParser +from datetime import datetime +from fileinput import FileInput +from subprocess import run, Popen, STDOUT, PIPE, CalledProcessError + + + +class JulesDocsRelease: + """Class which deploys the jules docs.""" + + def __init__(self, vnumber): + self.vnumber = str(vnumber) + self.changed = False + return + + def update_config(self, target): + """Update the sphinx configuration file.""" + + year = str(datetime.now().year) + + cr_pattern = re.compile(r"\s*copyright\s*=\s*.(\d+).") + vn_pattern = re.compile(r"\s*(release|version)\s*=\s*.([\d\.]+).") + + with FileInput(target, inplace=True) as fd: + # Update the copyright and version information in the + # sphinx config file + + for line in fd: + if match := cr_pattern.match(line): + if match.group(1) != year: + line = f"copyright = '{year}'\n" + self.changed = True + logging.info("Updated sphinx copyright year") + elif match := vn_pattern.match(line): + if match.group(2) != self.vnumber: + line = f"{match.group(1)} = '{self.vnumber}'\n" + self.changed = True + logging.info( + "Updated sphinx %s number to %s", + match.group(1), + self.vnumber, + ) + print(line, end="") + + return + + def update_index(self, target): + """Update the index page with the new release.""" + + # Check whether an update is required + with FileInput(target) as fd: + match = f'a href="vn{self.vnumber}"' + found = False + + for line in fd: + if match in line: + found = True + break + + if found: + # Stop if version is already present + return + + # Add the missing version link + with FileInput(target, inplace=True) as fd: + for line in fd: + if 'href="latest/index.html"' in line: + line += " " * 16 + line += ( + f'
  • vn{self.vnumber}
    • \n' + ) + self.changed = True + logging.info("Added reference to vn%s to index", self.vnumber) + print(line, end="") + + return + + def mkdocs(self): + """Run sphinx to build the HTML documentation.""" + + dest = f"vn{self.vnumber}" + + if not os.path.exists(dest): + # Build the sphinx documentation + cmd = [ + "sphinx-build", + "-qb", + "html", + "user_guide/doc/source", + f"vn{self.vnumber}", + ] + run(cmd, check=True) + logging.info("Successfully built the sphinx documentation") + + if os.path.exists(dest): + # Check directory exists and create a symlink + if os.path.islink("latest") and os.readlink("latest") != dest: + os.unlink("latest") + if not os.path.exists("latest"): + os.symlink(dest, "latest") + logging.info("Set latest link to %s", dest) + + return + + +def last_log_message(branch): + """Get the log message of the last commit to trunk.""" + + cmd = ["git", "log", "--pretty=format:message: %s", "--branches", branch, "-1"] + + with Popen(cmd, stdout=PIPE, stderr=STDOUT, encoding="utf-8") as proc: + message = "unknown update" + + for line in proc.stdout: + if line.startswith("message: "): + message = line.split(": ", 1)[-1] + break + + return message + + +def commit_changes(args): + """Commit any new change to the trunk.""" + + cmd = ["git", "add", "-A"] + run(cmd, check=False) + + cmd = ["git", "diff", "--cached", "--quiet"] + if run(cmd, check=False) == 0: + logging.info("no changes need to be committed") + + message = last_log_message(args.trunk_name) + message = f"Docs build for {message}" + + if args.no_commit: + # Skip the commit and push commands + logging.info("Need to commit change for %r", message) + return + + cmd = ["git", "commit", "--no-gpg-sign", "-a", "--quiet", "-m", message] + + run(cmd, check=True) + logging.info("Committed change %r", message) + run(["git", "push"], check=True) + logging.info("Pushed automatic commit") + + return + + +def main(): + """Main function.""" + + parser = ArgumentParser() + parser.add_argument("--verbose", action="store_true", help="enable verbose output") + parser.add_argument( + "--trunk-name", type=str, default="master", help="name of trunk" + ) + parser.add_argument( + "--no-commit", action="store_true", help="do not commit the changes" + ) + parser.add_argument("release", type=str, help="github release reference") + args = parser.parse_args() + + match = re.match(r".*vn?([\.\d]+)-*\S*$", args.release) + if match: + vnumber = match.group(1) + else: + parser.error(f"unable to identify version number '{args.release}'") + + if args.verbose: + logging.basicConfig(level=logging.INFO, format="%(message)s") + + release = JulesDocsRelease(vnumber) + + try: + release.update_config("user_guide/doc/source/conf.py") + release.mkdocs() + release.update_index("index.html") + except (FileNotFoundError, CalledProcessError) as error: + logging.error(str(error)) + raise SystemExit(1) from error + + if release.changed: + # There are at least some updates to apply + commit_changes(args) + + else: + logging.info("No changes made") + raise SystemExit(2) + + return + + +if __name__ == "__main__": + main() diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index 996d1cec..068bc797 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -1,5 +1,14 @@ -# This workflow ensures that required environment is activated, and ensures -# that the JULES Sphinx documenation builds correctly. +--- +# This workflow builds the JULES Sphinx documenation. +# +# Where the triggering event does not match the master branch on the +# main jules docs repository, the action limits itself to a test +# build. +# +# Where the event is a push to master on the main repository, the +# workflow checks for documentation that matches the most recent +# release tag, install it if necessary, and commits any changes to +# make the documentation visible via github pages. name: build_docs @@ -18,13 +27,58 @@ jobs: steps: - name: checkout uses: actions/checkout@v4 + with: + fetch-depth: 0 + fetch-tags: true - - name: Build documentation + - name: Setup conda run: | conda update conda - conda env create -f environment.yml + conda env create -f environment.yml + echo ":heavy_check_mark: Set up conda environment" >> $GITHUB_STEP_SUMMARY + + - name: Test documentation + run: | + eval "$(conda shell.bash hook)" + conda activate jules-user-guide + pushd user_guide/doc + # Add status of tests to the summary + if make html; then + echo ":heavy_check_mark: Documentation tests passed" >> $GITHUB_STEP_SUMMARY + else + echo ":x: Documentation tests failed" >> $GITHUB_STEP_SUMMARY + exit 1 + fi + popd + if: ${{ github.repository != 'jules-lsm/jules-lsm.github.io' + || github.ref != 'refs/heads/master' }} + + - name: Deploy documentation + run: | eval "$(conda shell.bash hook)" conda activate jules-user-guide - cd user_guide/doc - make html + # Setup some git things + git config --global user.email "umsysteam@metoffice.gov.uk" + git config --global user.name "Jules Bot" + TAG=$( git describe --tags | sed "s/-.*//" ) + + # Capture the output status of the command, no matter what + # it is, without causing the workflow to fail if it is + # non-zero + python3 .github/scripts/release.py --verbose $TAG && STATUS=$? || STATUS=$? + + # Add a message to the summary + if [[ $STATUS = 0 ]]; then + echo ":heavy_check_mark: Documentation for $TAG deployed" >> $GITHUB_STEP_SUMMARY + elif [[ $STATUS = 1 ]]; then + echo ":x: Documentation for $TAG failed" >> $GITHUB_STEP_SUMMARY + exit 1 + elif [[ $STATUS = 2 ]]; then + echo ":speech_balloon: Documentation for $TAG is up to date" >> $GITHUB_STEP_SUMMARY + fi + exit 0 + if: ${{ github.repository == 'jules-lsm/jules-lsm.github.io' + && github.ref == 'refs/heads/master' + && (github.event_name == 'push' + || github.event_name == 'workflow_dispatch') }} From 131b273bd17399856344762dd6f2336fb35c7bef Mon Sep 17 00:00:00 2001 From: eleanorgb Date: Tue, 4 Jun 2024 16:44:44 +0100 Subject: [PATCH 21/24] changes to description of z_burn_max --- user_guide/doc/source/namelists/jules_soil_biogeochem.nml.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide/doc/source/namelists/jules_soil_biogeochem.nml.rst b/user_guide/doc/source/namelists/jules_soil_biogeochem.nml.rst index 6968cb2a..dd8da1bf 100644 --- a/user_guide/doc/source/namelists/jules_soil_biogeochem.nml.rst +++ b/user_guide/doc/source/namelists/jules_soil_biogeochem.nml.rst @@ -212,7 +212,7 @@ If using the ECOSSE soil model, most soil parameters are read from a separate fi :type: real :default: 0.2 - Parameter controlling the depth to which fire burns soil litter carbon in meters. At depths shallower than this value, the fire can burn soil carbon in the two litter pools (dpm and rpm). If z_burn_max falls within a layer only a proportion of the soil carbon is burnt. Only used with layered soil carbon scheme (:nml:mem:`l_layeredc` = TRUE) and fire (either :nml:mem:`JULES_VEGETATION::l_trif_fire` or :nml:mem:`JULES_VEGETATION::l_inferno` or both). + Parameter controlling the depth to which fire burns soil litter carbon in meters. At depths shallower than this value, the fire can burn soil carbon in the two litter pools (dpm and rpm). If z_burn_max falls within a layer only a proportion of the soil carbon is burnt. Only used with layered soil carbon scheme (:nml:mem:`l_layeredc` = TRUE) and fire (either :nml:mem:`JULES_VEGETATION::l_trif_fire` or :nml:mem:`JULES_VEGETATION::l_inferno` or both). In reality the burn depth varies so please check whether the default value of 0.2 is suitable for your application. .. nml:group:: Parameters for the 4-pool- or ECOSSE-based models (only used if :nml:mem:`soil_bgc_model` = 2 or 3): From f3c368e8aec128dda72c573041615c864758203a Mon Sep 17 00:00:00 2001 From: Sam Clarke-Green Date: Thu, 20 Jun 2024 15:46:21 +0100 Subject: [PATCH 22/24] Deploy documentation updates to gh-pages Change the workflow and the release.py script to deploy to a gh-pages branch rather than using the master branch as is presently the case. This should bypass problems associated with the branch controls on main. In order to take advantage of this change, the github repo settings need to be updated to serve the documentation from the gh-pages branch. --- .github/scripts/release.py | 20 +++++++++++++++++++- .github/workflows/build_docs.yml | 2 +- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/.github/scripts/release.py b/.github/scripts/release.py index a4e4d536..9f09532b 100755 --- a/.github/scripts/release.py +++ b/.github/scripts/release.py @@ -153,7 +153,12 @@ def commit_changes(args): run(cmd, check=True) logging.info("Committed change %r", message) - run(["git", "push"], check=True) + + # Push the update to the upstream repo and branch + cmd = ["git", "push", "origin"] + if args.gh_pages: + cmd.append("gh-pages") + run(cmd, check=True) logging.info("Pushed automatic commit") return @@ -170,6 +175,9 @@ def main(): parser.add_argument( "--no-commit", action="store_true", help="do not commit the changes" ) + parser.add_argument( + "--gh-pages", action="store_true", help="deploy to a gh-pages branch" + ) parser.add_argument("release", type=str, help="github release reference") args = parser.parse_args() @@ -185,6 +193,16 @@ def main(): release = JulesDocsRelease(vnumber) try: + if args.gh_pages: + # Create a new gh-pages branch and replace the contents + # with the current trunk before checking it out + cmd = ["git", "branch", "-C", "gh-pages"] + run(cmd, check=True) + logging.info("Created new gh-pages branch") + cmd = ["git", "checkout", "gh-pages"] + run(cmd, check=True) + logging.info("Checking out gh-pages branch") + release.update_config("user_guide/doc/source/conf.py") release.mkdocs() release.update_index("index.html") diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index 068bc797..af07e555 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -66,7 +66,7 @@ jobs: # Capture the output status of the command, no matter what # it is, without causing the workflow to fail if it is # non-zero - python3 .github/scripts/release.py --verbose $TAG && STATUS=$? || STATUS=$? + python3 .github/scripts/release.py --verbose $TAG --gh-pages && STATUS=$? || STATUS=$? # Add a message to the summary if [[ $STATUS = 0 ]]; then From ef40349c80a84c9c4b6baeff96b819440bd8acd7 Mon Sep 17 00:00:00 2001 From: doucla Date: Fri, 5 Jul 2024 15:52:10 +0100 Subject: [PATCH 23/24] Release notes for vn7.6. (#53) * Added release notes for vn7.6. Minor tweaks (corrections) to a few existing files. * Everything added. --- .../namelists/jules_soil_biogeochem.nml.rst | 2 +- .../doc/source/release_notes/JULES7-5.rst | 2 +- .../doc/source/release_notes/JULES7-6.rst | 45 +++++++++++++++++++ .../doc/source/release_notes/contents.rst | 1 + 4 files changed, 48 insertions(+), 2 deletions(-) create mode 100644 user_guide/doc/source/release_notes/JULES7-6.rst diff --git a/user_guide/doc/source/namelists/jules_soil_biogeochem.nml.rst b/user_guide/doc/source/namelists/jules_soil_biogeochem.nml.rst index dd8da1bf..a138b998 100644 --- a/user_guide/doc/source/namelists/jules_soil_biogeochem.nml.rst +++ b/user_guide/doc/source/namelists/jules_soil_biogeochem.nml.rst @@ -212,7 +212,7 @@ If using the ECOSSE soil model, most soil parameters are read from a separate fi :type: real :default: 0.2 - Parameter controlling the depth to which fire burns soil litter carbon in meters. At depths shallower than this value, the fire can burn soil carbon in the two litter pools (dpm and rpm). If z_burn_max falls within a layer only a proportion of the soil carbon is burnt. Only used with layered soil carbon scheme (:nml:mem:`l_layeredc` = TRUE) and fire (either :nml:mem:`JULES_VEGETATION::l_trif_fire` or :nml:mem:`JULES_VEGETATION::l_inferno` or both). In reality the burn depth varies so please check whether the default value of 0.2 is suitable for your application. + Parameter controlling the depth to which fire burns soil litter carbon in metres. At depths shallower than this value, the fire can burn soil carbon in the two litter pools (dpm and rpm). If z_burn_max falls within a layer only a proportion of the soil carbon is burnt. Only used with layered soil carbon scheme (:nml:mem:`l_layeredc` = TRUE) and fire (either :nml:mem:`JULES_VEGETATION::l_trif_fire` or :nml:mem:`JULES_VEGETATION::l_inferno` or both). In reality the burn depth varies so please check whether the default value of 0.2 is suitable for your application. .. nml:group:: Parameters for the 4-pool- or ECOSSE-based models (only used if :nml:mem:`soil_bgc_model` = 2 or 3): diff --git a/user_guide/doc/source/release_notes/JULES7-5.rst b/user_guide/doc/source/release_notes/JULES7-5.rst index 97bb55fd..dbcf37d6 100644 --- a/user_guide/doc/source/release_notes/JULES7-5.rst +++ b/user_guide/doc/source/release_notes/JULES7-5.rst @@ -18,7 +18,7 @@ General/Technical changes ------------------------- * Added water tracers to the hydrology and snow schemes - part of ongoing work to add water tracers/isotopes to JULES. (#1391, 1465) - * For runs with rivers, the new option :nml:mem:`JULES_RIVERS::l_find_grid` can be used to avoid requiring values for variables related to the model grid. This also revises how the area searched for river points is set up. (#1380) + * For runs with rivers, the new option :nml:mem:`JULES_RIVERS_PROPS::l_find_grid` can be used to avoid requiring values for variables related to the model grid. This also revises how the area searched for river points is set up. (#1380) * IMOGEN now reads netcdf files for driving data. (#1265) * :nml:mem:`JULES_RIVERS::trip_globe_shape` allows the TRIP river routing scheme to consider the Earth as either spherical or ellipsoidal (a more accurate approximation but inconsistent with other component models - e.g. UM and NEMO - which assume the Earth is spherical. Note that this change only affects the UM version of TRIP. (#1374) * Optimisation and OpenMP efficiency improvements in various places. (#1471) diff --git a/user_guide/doc/source/release_notes/JULES7-6.rst b/user_guide/doc/source/release_notes/JULES7-6.rst new file mode 100644 index 00000000..5d004e24 --- /dev/null +++ b/user_guide/doc/source/release_notes/JULES7-6.rst @@ -0,0 +1,45 @@ +JULES version 7.6 Release Notes +=============================== + +The JULES vn7.6 release consists of approximately 19 tickets from 10 authors, including work by many other people. + +Full details of the tickets committed for JULES vn7.6 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #1512. + +General/Technical changes +------------------------- + + * Changes to how river ancillary files are processed. (#1512) + * Added water tracers to the UM_TRIP river routing. (#1466) + * Completion of the water tracer code development so water tracers can track water through the UM and JULES. (#1389) + * Allowed flexible number of soil layers in the UM atmospheric model. (#1188) + * Removed further tab characters. (#1511) + * Optimisation changes for JULES standalone. (#1501) + * 1-D fields for surface and sub-surface runoff coupling between LFRic and TRIP replaced with 2-D coupling. (#1527) + * Altered usage of the model_type option for LFRic use cases. (#1521) + * Updated CodeOwners file. (#1538) + +Bugs fixed +---------- + + * Add a burn depth parameter :nml:mem:`JULES_SOIL_BIOGEOCHEM::z_burn_max` for when layered soil carbon is used so that fire only consumes soil carbon from above the burn depth. (#1514) + * Fix to stop NaNs appearing in the agriculture fraction (frac_agr) with the TRIFFID vegetation model. (#1526) + * Fixed JULES upgrade macro code for Rose2 and related fix for how JULES version files are imported. (#1508, 1531) + * Fixes for build on Met Office XC40 system. (#1513) + + +Changes to testing +------------------ + + * Deployment optimisations for Met Office rose stem jobs, and tweaks to nccmp jobs. (#1519, 1518, 1536, 1537) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#1532) + + +Documentation can be viewed on the github page ``_. + diff --git a/user_guide/doc/source/release_notes/contents.rst b/user_guide/doc/source/release_notes/contents.rst index f225394a..d28c7358 100644 --- a/user_guide/doc/source/release_notes/contents.rst +++ b/user_guide/doc/source/release_notes/contents.rst @@ -3,6 +3,7 @@ Release notes ============= .. toctree:: + JULES7-6 JULES7-5 JULES7-4 JULES7-3 From a8f5afa43f907e6e10b5de77293d469ab54d88b3 Mon Sep 17 00:00:00 2001 From: Sam Clarke-Green Date: Tue, 9 Jul 2024 14:21:46 +0100 Subject: [PATCH 24/24] Use a persistent gh-pages branch for documentation Prompted by comments from a reviewer, this modifies the workflow to use a persistent gh-pages branch to hold the documentation. This ensures that links created when a version tag is created endure across multiple releases. This is achieved by attempting to check out an existing gh-pages branch and only using checkout -b when this fails. This also adds the --force flag to the push command that updates the upstream branch to deal with spurious errors which result from the merger of the trunk into the docs branch. --- .github/scripts/release.py | 38 +++++++++++++++++++++++--------- .github/workflows/build_docs.yml | 8 ++++--- 2 files changed, 32 insertions(+), 14 deletions(-) diff --git a/.github/scripts/release.py b/.github/scripts/release.py index 9f09532b..6e1f148a 100755 --- a/.github/scripts/release.py +++ b/.github/scripts/release.py @@ -16,7 +16,6 @@ from subprocess import run, Popen, STDOUT, PIPE, CalledProcessError - class JulesDocsRelease: """Class which deploys the jules docs.""" @@ -155,7 +154,7 @@ def commit_changes(args): logging.info("Committed change %r", message) # Push the update to the upstream repo and branch - cmd = ["git", "push", "origin"] + cmd = ["git", "push", "--force", "origin"] if args.gh_pages: cmd.append("gh-pages") run(cmd, check=True) @@ -164,6 +163,30 @@ def commit_changes(args): return +def setup_pages_branch(args, branch): + """Setup pages branch for documentation build.""" + + # Check out the docs branch or create it if it doesn't exist + cmd = ["git", "checkout", branch] + result = run(cmd, check=False) + if result.returncode == 0: + logging.info("Checking out %s branch", branch) + else: + # Add the branch option and retry the checkout + cmd.insert(-1, "-b") + run(cmd, check=True) + logging.info("Created branch %s", branch) + + # Merge changes from the trunk into the docs branch but defer + # committing until the docs have been built. If there is a + # conflict, resolve by overwriting with the copy from the trunk + cmd = ["git", "merge", "-v", "-X", "theirs", "--no-commit", args.trunk_name] + run(cmd, check=True) + logging.info("Merging changes from %s to %s branch", args.trunk_name, branch) + + return + + def main(): """Main function.""" @@ -194,19 +217,12 @@ def main(): try: if args.gh_pages: - # Create a new gh-pages branch and replace the contents - # with the current trunk before checking it out - cmd = ["git", "branch", "-C", "gh-pages"] - run(cmd, check=True) - logging.info("Created new gh-pages branch") - cmd = ["git", "checkout", "gh-pages"] - run(cmd, check=True) - logging.info("Checking out gh-pages branch") + setup_pages_branch(args, "gh-pages") release.update_config("user_guide/doc/source/conf.py") release.mkdocs() release.update_index("index.html") - except (FileNotFoundError, CalledProcessError) as error: + except (FileNotFoundError, CalledProcessError) as error: logging.error(str(error)) raise SystemExit(1) from error diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index af07e555..b2db98ea 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -7,8 +7,9 @@ # # Where the event is a push to master on the main repository, the # workflow checks for documentation that matches the most recent -# release tag, install it if necessary, and commits any changes to -# make the documentation visible via github pages. +# release tag and adds it to the gh-pages branch as necessary. The +# documentation can be published by configuring the repository to +# use the gh-pages branch. name: build_docs @@ -66,7 +67,8 @@ jobs: # Capture the output status of the command, no matter what # it is, without causing the workflow to fail if it is # non-zero - python3 .github/scripts/release.py --verbose $TAG --gh-pages && STATUS=$? || STATUS=$? + python3 .github/scripts/release.py --verbose --gh-pages $TAG \ + && STATUS=$? || STATUS=$? # Add a message to the summary if [[ $STATUS = 0 ]]; then