From a5d87bc73a8979d17739c17800424d6306b09dd1 Mon Sep 17 00:00:00 2001 From: Yaswant Pradhan <2984440+yaswant@users.noreply.github.com> Date: Tue, 25 Nov 2025 10:27:44 +0000 Subject: [PATCH 1/3] Import user_guide from jules-lsm.github.io --- .github/scripts/release.py | 241 ++ .github/workflows/build_docs.yml | 92 + .gitignore | 24 + doc/Makefile | 153 ++ doc/make.bat | 35 + doc/source/_static/jules-tweaks.css | 207 ++ doc/source/_templates/localtoc.html | 2 + .../building-and-running/considerations.rst | 35 + doc/source/building-and-running/fcm.rst | 253 +++ doc/source/building-and-running/intro.rst | 17 + .../required-software.rst | 37 + doc/source/building-and-running/rose.rst | 133 ++ .../building-and-running/running-jules.rst | 82 + doc/source/code/contents.rst | 8 + doc/source/code/io.rst | 194 ++ doc/source/code/io_modular_structure.png | Bin 0 -> 24670 bytes doc/source/code/known-limitations.rst | 19 + doc/source/code/records_in_file.png | Bin 0 -> 5767 bytes doc/source/conf.py | 287 +++ doc/source/examples.rst | 8 + doc/source/index.rst | 31 + doc/source/input/ascii.rst | 52 + doc/source/input/file-name-templating.rst | 136 ++ doc/source/input/interp_examples.png | Bin 0 -> 90819 bytes doc/source/input/netcdf.rst | 9 + doc/source/input/overview.rst | 13 + doc/source/input/principles.rst | 23 + doc/source/input/temporal-interpolation.rst | 63 + .../input/time_templating_flow_diagram.png | Bin 0 -> 61631 bytes doc/source/jules_logo_html.png | Bin 0 -> 15977 bytes doc/source/jules_logo_pdf.png | Bin 0 -> 204682 bytes doc/source/namelists/ancillaries.nml.rst | 2004 +++++++++++++++++ doc/source/namelists/cable_pftparm.nml.rst | 413 ++++ .../namelists/cable_prognostics.nml.rst | 126 ++ doc/source/namelists/cable_soilparm.nml.rst | 104 + .../namelists/cable_surface_types.nml.rst | 73 + doc/source/namelists/contents.rst | 56 + doc/source/namelists/crop_params.nml.rst | 245 ++ doc/source/namelists/drive.nml.rst | 587 +++++ doc/source/namelists/fire.nml.rst | 60 + doc/source/namelists/imogen.nml.rst | 423 ++++ .../namelists/initial_conditions.nml.rst | 516 +++++ doc/source/namelists/intro.rst | 35 + doc/source/namelists/jules_deposition.nml.rst | 418 ++++ doc/source/namelists/jules_hydrology.nml.rst | 217 ++ doc/source/namelists/jules_irrig.nml.rst | 141 ++ .../namelists/jules_prnt_control.nml.rst | 27 + doc/source/namelists/jules_radiation.nml.rst | 310 +++ doc/source/namelists/jules_rivers.nml.rst | 362 +++ doc/source/namelists/jules_snow.nml.rst | 648 ++++++ doc/source/namelists/jules_soil.nml.rst | 244 ++ .../namelists/jules_soil_biogeochem.nml.rst | 443 ++++ .../namelists/jules_soil_ecosse.nml.rst | 409 ++++ doc/source/namelists/jules_surface.nml.rst | 309 +++ .../namelists/jules_surface_types.nml.rst | 326 +++ doc/source/namelists/jules_vegetation.nml.rst | 1052 +++++++++ .../namelists/jules_water_resources.nml.rst | 250 ++ .../namelists/model_environment.nml.rst | 84 + doc/source/namelists/model_grid.nml.rst | 928 ++++++++ doc/source/namelists/nveg_params.nml.rst | 144 ++ doc/source/namelists/oasis_rivers.nml.rst | 97 + doc/source/namelists/output.nml.rst | 354 +++ doc/source/namelists/pft_params.nml.rst | 1033 +++++++++ doc/source/namelists/prescribed_data.nml.rst | 288 +++ doc/source/namelists/red_parms.nml.rst | 120 + doc/source/namelists/science_fixes.nml.rst | 196 ++ doc/source/namelists/timesteps.nml.rst | 348 +++ doc/source/namelists/triffid_params.nml.rst | 180 ++ doc/source/namelists/urban.nml.rst | 193 ++ doc/source/output-variables.rst | 1456 ++++++++++++ doc/source/output.rst | 75 + doc/source/overview/intro.rst | 8 + doc/source/overview/key-switches.rst | 18 + doc/source/overview/overview.rst | 11 + doc/source/release_notes/JULES1-0.rst | 4 + doc/source/release_notes/JULES2-0.rst | 12 + doc/source/release_notes/JULES2-1.rst | 26 + doc/source/release_notes/JULES2-2.rst | 13 + doc/source/release_notes/JULES3-0.rst | 18 + doc/source/release_notes/JULES3-1.rst | 36 + doc/source/release_notes/JULES3-2.rst | 49 + doc/source/release_notes/JULES3-3.rst | 60 + doc/source/release_notes/JULES3-4.rst | 49 + doc/source/release_notes/JULES4-0.rst | 59 + doc/source/release_notes/JULES4-1.rst | 56 + doc/source/release_notes/JULES4-2.rst | 48 + doc/source/release_notes/JULES4-3.rst | 57 + doc/source/release_notes/JULES4-4.rst | 43 + doc/source/release_notes/JULES4-5.rst | 48 + doc/source/release_notes/JULES4-6.rst | 57 + doc/source/release_notes/JULES4-7.rst | 97 + doc/source/release_notes/JULES4-8.rst | 69 + doc/source/release_notes/JULES4-9.rst | 65 + doc/source/release_notes/JULES5-0.rst | 50 + doc/source/release_notes/JULES5-1.rst | 62 + doc/source/release_notes/JULES5-2.rst | 75 + doc/source/release_notes/JULES5-3.rst | 58 + doc/source/release_notes/JULES5-4.rst | 61 + doc/source/release_notes/JULES5-5.rst | 46 + doc/source/release_notes/JULES5-6.rst | 45 + doc/source/release_notes/JULES5-7.rst | 62 + doc/source/release_notes/JULES5-8.rst | 42 + doc/source/release_notes/JULES5-9.rst | 55 + doc/source/release_notes/JULES6-0.rst | 48 + doc/source/release_notes/JULES6-1.rst | 51 + doc/source/release_notes/JULES6-2.rst | 50 + doc/source/release_notes/JULES6-3.rst | 60 + doc/source/release_notes/JULES7-0.rst | 64 + doc/source/release_notes/JULES7-1.rst | 53 + doc/source/release_notes/JULES7-2.rst | 49 + doc/source/release_notes/JULES7-3.rst | 48 + doc/source/release_notes/JULES7-4.rst | 56 + doc/source/release_notes/JULES7-5.rst | 58 + doc/source/release_notes/JULES7-6.rst | 45 + doc/source/release_notes/JULES7-7.rst | 37 + doc/source/release_notes/JULES7-8.rst | 41 + doc/source/release_notes/JULES7-9.rst | 54 + doc/source/release_notes/JULES8-0.rst | 47 + doc/source/release_notes/contents.rst | 52 + doc/sphinxext/pygments_fcm_make_conf_lexer.py | 65 + doc/sphinxext/pygments_fortran_nml_lexer.py | 59 + doc/sphinxext/sphinx_nml_domain.py | 355 +++ 122 files changed, 20199 insertions(+) create mode 100755 .github/scripts/release.py create mode 100644 .github/workflows/build_docs.yml create mode 100644 .gitignore create mode 100644 doc/Makefile create mode 100644 doc/make.bat create mode 100644 doc/source/_static/jules-tweaks.css create mode 100644 doc/source/_templates/localtoc.html create mode 100644 doc/source/building-and-running/considerations.rst create mode 100644 doc/source/building-and-running/fcm.rst create mode 100644 doc/source/building-and-running/intro.rst create mode 100644 doc/source/building-and-running/required-software.rst create mode 100644 doc/source/building-and-running/rose.rst create mode 100644 doc/source/building-and-running/running-jules.rst create mode 100644 doc/source/code/contents.rst create mode 100644 doc/source/code/io.rst create mode 100644 doc/source/code/io_modular_structure.png create mode 100644 doc/source/code/known-limitations.rst create mode 100644 doc/source/code/records_in_file.png create mode 100644 doc/source/conf.py create mode 100644 doc/source/examples.rst create mode 100644 doc/source/index.rst create mode 100644 doc/source/input/ascii.rst create mode 100644 doc/source/input/file-name-templating.rst create mode 100644 doc/source/input/interp_examples.png create mode 100644 doc/source/input/netcdf.rst create mode 100644 doc/source/input/overview.rst create mode 100644 doc/source/input/principles.rst create mode 100644 doc/source/input/temporal-interpolation.rst create mode 100644 doc/source/input/time_templating_flow_diagram.png create mode 100644 doc/source/jules_logo_html.png create mode 100644 doc/source/jules_logo_pdf.png create mode 100644 doc/source/namelists/ancillaries.nml.rst create mode 100644 doc/source/namelists/cable_pftparm.nml.rst create mode 100644 doc/source/namelists/cable_prognostics.nml.rst create mode 100644 doc/source/namelists/cable_soilparm.nml.rst create mode 100644 doc/source/namelists/cable_surface_types.nml.rst create mode 100644 doc/source/namelists/contents.rst create mode 100644 doc/source/namelists/crop_params.nml.rst create mode 100644 doc/source/namelists/drive.nml.rst create mode 100644 doc/source/namelists/fire.nml.rst create mode 100644 doc/source/namelists/imogen.nml.rst create mode 100644 doc/source/namelists/initial_conditions.nml.rst create mode 100644 doc/source/namelists/intro.rst create mode 100644 doc/source/namelists/jules_deposition.nml.rst create mode 100644 doc/source/namelists/jules_hydrology.nml.rst create mode 100644 doc/source/namelists/jules_irrig.nml.rst create mode 100644 doc/source/namelists/jules_prnt_control.nml.rst create mode 100644 doc/source/namelists/jules_radiation.nml.rst create mode 100644 doc/source/namelists/jules_rivers.nml.rst create mode 100644 doc/source/namelists/jules_snow.nml.rst create mode 100644 doc/source/namelists/jules_soil.nml.rst create mode 100644 doc/source/namelists/jules_soil_biogeochem.nml.rst create mode 100644 doc/source/namelists/jules_soil_ecosse.nml.rst create mode 100644 doc/source/namelists/jules_surface.nml.rst create mode 100644 doc/source/namelists/jules_surface_types.nml.rst create mode 100644 doc/source/namelists/jules_vegetation.nml.rst create mode 100644 doc/source/namelists/jules_water_resources.nml.rst create mode 100644 doc/source/namelists/model_environment.nml.rst create mode 100644 doc/source/namelists/model_grid.nml.rst create mode 100644 doc/source/namelists/nveg_params.nml.rst create mode 100644 doc/source/namelists/oasis_rivers.nml.rst create mode 100644 doc/source/namelists/output.nml.rst create mode 100644 doc/source/namelists/pft_params.nml.rst create mode 100644 doc/source/namelists/prescribed_data.nml.rst create mode 100644 doc/source/namelists/red_parms.nml.rst create mode 100644 doc/source/namelists/science_fixes.nml.rst create mode 100644 doc/source/namelists/timesteps.nml.rst create mode 100644 doc/source/namelists/triffid_params.nml.rst create mode 100644 doc/source/namelists/urban.nml.rst create mode 100644 doc/source/output-variables.rst create mode 100644 doc/source/output.rst create mode 100644 doc/source/overview/intro.rst create mode 100644 doc/source/overview/key-switches.rst create mode 100644 doc/source/overview/overview.rst create mode 100644 doc/source/release_notes/JULES1-0.rst create mode 100644 doc/source/release_notes/JULES2-0.rst create mode 100644 doc/source/release_notes/JULES2-1.rst create mode 100644 doc/source/release_notes/JULES2-2.rst create mode 100644 doc/source/release_notes/JULES3-0.rst create mode 100644 doc/source/release_notes/JULES3-1.rst create mode 100644 doc/source/release_notes/JULES3-2.rst create mode 100644 doc/source/release_notes/JULES3-3.rst create mode 100644 doc/source/release_notes/JULES3-4.rst create mode 100644 doc/source/release_notes/JULES4-0.rst create mode 100644 doc/source/release_notes/JULES4-1.rst create mode 100644 doc/source/release_notes/JULES4-2.rst create mode 100644 doc/source/release_notes/JULES4-3.rst create mode 100644 doc/source/release_notes/JULES4-4.rst create mode 100644 doc/source/release_notes/JULES4-5.rst create mode 100644 doc/source/release_notes/JULES4-6.rst create mode 100644 doc/source/release_notes/JULES4-7.rst create mode 100644 doc/source/release_notes/JULES4-8.rst create mode 100644 doc/source/release_notes/JULES4-9.rst create mode 100644 doc/source/release_notes/JULES5-0.rst create mode 100644 doc/source/release_notes/JULES5-1.rst create mode 100644 doc/source/release_notes/JULES5-2.rst create mode 100644 doc/source/release_notes/JULES5-3.rst create mode 100644 doc/source/release_notes/JULES5-4.rst create mode 100644 doc/source/release_notes/JULES5-5.rst create mode 100644 doc/source/release_notes/JULES5-6.rst create mode 100644 doc/source/release_notes/JULES5-7.rst create mode 100644 doc/source/release_notes/JULES5-8.rst create mode 100644 doc/source/release_notes/JULES5-9.rst create mode 100644 doc/source/release_notes/JULES6-0.rst create mode 100644 doc/source/release_notes/JULES6-1.rst create mode 100644 doc/source/release_notes/JULES6-2.rst create mode 100644 doc/source/release_notes/JULES6-3.rst create mode 100644 doc/source/release_notes/JULES7-0.rst create mode 100644 doc/source/release_notes/JULES7-1.rst create mode 100644 doc/source/release_notes/JULES7-2.rst create mode 100644 doc/source/release_notes/JULES7-3.rst create mode 100644 doc/source/release_notes/JULES7-4.rst create mode 100644 doc/source/release_notes/JULES7-5.rst create mode 100644 doc/source/release_notes/JULES7-6.rst create mode 100644 doc/source/release_notes/JULES7-7.rst create mode 100644 doc/source/release_notes/JULES7-8.rst create mode 100644 doc/source/release_notes/JULES7-9.rst create mode 100644 doc/source/release_notes/JULES8-0.rst create mode 100644 doc/source/release_notes/contents.rst create mode 100644 doc/sphinxext/pygments_fcm_make_conf_lexer.py create mode 100644 doc/sphinxext/pygments_fortran_nml_lexer.py create mode 100644 doc/sphinxext/sphinx_nml_domain.py diff --git a/.github/scripts/release.py b/.github/scripts/release.py new file mode 100755 index 00000000..6e1f148a --- /dev/null +++ b/.github/scripts/release.py @@ -0,0 +1,241 @@ +#!/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) + + # Push the update to the upstream repo and branch + cmd = ["git", "push", "--force", "origin"] + if args.gh_pages: + cmd.append("gh-pages") + run(cmd, check=True) + logging.info("Pushed automatic commit") + + 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.""" + + 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( + "--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() + + 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: + if args.gh_pages: + 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: + 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 new file mode 100644 index 00000000..be1ccc3c --- /dev/null +++ b/.github/workflows/build_docs.yml @@ -0,0 +1,92 @@ +--- +# 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 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 + +# Controls when the action will run +on: + push: + branches: [master] + 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 + with: + fetch-depth: 0 + fetch-tags: true + + - name: Setup conda + run: | + conda update conda + 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 build test passed" >> $GITHUB_STEP_SUMMARY + else + echo ":x: Documentation build test failed" >> $GITHUB_STEP_SUMMARY + exit 1 + fi + if make linkcheck; then + echo ":heavy_check_mark: Documentation link checking passed" >> $GITHUB_STEP_SUMMARY + else + echo ":x: Documentation link checking failed" >> $GITHUB_STEP_SUMMARY + 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 + + # 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 --gh-pages $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') }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..6e0f858c --- /dev/null +++ b/.gitignore @@ -0,0 +1,24 @@ +*~ +__pycache__/ +results/*.png +results/*.txt +processed_data/*.dat +.*.sw? + +#ignore build output +/build/ +_build/ +user_guide/doc/_build +user_guide/doc/build + +#ignore VS Code files +/.idea + +#ignore envs +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..c360915f --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,153 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/JULESJointUKLandEnvironmentSimulator.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/JULESJointUKLandEnvironmentSimulator.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/JULESJointUKLandEnvironmentSimulator" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/JULESJointUKLandEnvironmentSimulator" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 00000000..061f32f9 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/source/_static/jules-tweaks.css b/doc/source/_static/jules-tweaks.css new file mode 100644 index 00000000..55d698a5 --- /dev/null +++ b/doc/source/_static/jules-tweaks.css @@ -0,0 +1,207 @@ +pre { + background-color : #f2f8ff; +} + +tt { + background-color : #f1f5f7; + border : 1px solid #C6C9CB; + padding : 2px 4px; +} + +dt tt:only-child { + display : inline-block; + margin-bottom : 2px; +} + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt, a tt, dl.member dt tt { + border : 0; + padding : 0; + margin : 0; +} + +a tt { + color : inherit; +} + +p.rubric { + padding-top : 5px; + border-top : 1px solid #C6C9CB; + padding-left : 10px; +} + +table.footnote { + margin : 0px 10px; +} + +div.sphinxsidebar { + width : 20%; +} + +div.bodywrapper { + margin : 0 0 0 20%; +} + +div.sphinxsidebarwrapper { + padding-top : 10px; +} + +div.sphinxsidebar p { + padding : 5px 10px; + margin-top : 0; +} + + +/* Namelist member formatting */ +dl { + margin : 0; +} + +dl > dd { + margin-top : 5px; + margin-bottom : 15px; +} + +dl > dd:empty { + margin-top : 0px; + margin-bottom : 0px; +} + +dl.member > dt { + font-size : 1.1em; +} + +dl.member > dd { + margin-bottom : 25px; +} + +dl.member > dd:empty { + margin-bottom : 0px; +} + + +/* Admonition stuff */ +div.admonition { + padding : 7px 15px 15px; + border : 1px solid #C6C9CB; +} + +div.admonition p.admonition-title { + position : relative; + top : -7px; + display : block; + background-color : #e1e5e7; + border-bottom : 1px solid #C6C9CB; + margin : -7px -15px 0px; + padding : 5px 15px; + font-size : 1.1em; +} + +p.admonition-title:after { + content : ""; +} + +div.admonition p.admonition-title + p { + display : block; + margin-top : 5px; +} + +div.admonition p.admonition-title + * { + margin-top : 5px; +} + +div.admonition p.last, div.admonition div.last, div.admonition ul.last, div.admonition ol.last { + margin-bottom : 0px; +} + +div.admonition dl.last > dd { + margin-bottom : 0; +} + +div.admonition dl.last > dd > :last-child { + margin-bottom : 0; +} + +tt.descclassname { + font-weight : normal; +} + +dt { + font-weight : bold; +} + +div.warning { + border : 1px solid #ff5050; +} + +div.warning p.admonition-title { + border-bottom : 1px solid #ff5050; + background-color : #ff8080; +} + + +/* Tables */ +table.docutils th, table.docutils td { + border : 1px solid #C6C9CB !important; + padding : 7px 10px; +} + +table.docutils th { + background-color : #e1e5e7; +} + +table.docutils td[colspan] { + background-color : #ebeff1; + font-weight : bold; +} + +table.docutils td .last { + margin-bottom : 0; +} + +table.docutils tr.row-odd { + background-color : #f2f8ff; +} + + +table.field-list { + margin-top : 5px; +} + +table.field-list tr.row-odd { + background-color : transparent; +} + +table.field-list th, table.field-list td { + padding : 3px 8px 3px 5px; +} + +table.field-list th { + text-align : right; +} + +table.field-list td.field-body { + text-align : center; + min-width : 150px; + font-family : monospace; +} + + +/* Figures */ +div.figure { + text-align : center; +} + +div.figure p.caption { + font-weight : bold; + font-size : 0.9em; +} + +div.figure p.caption:before { + content : "Figure: " +} + +div.figure img { + border: 1px solid #C6C9CB; + box-shadow: 1px 1px 1px #D8D8D8; + padding : 10px; +} diff --git a/doc/source/_templates/localtoc.html b/doc/source/_templates/localtoc.html new file mode 100644 index 00000000..bf18c4c1 --- /dev/null +++ b/doc/source/_templates/localtoc.html @@ -0,0 +1,2 @@ +

    {{ _('Table Of Contents') }}

    +{{ toctree() }} diff --git a/doc/source/building-and-running/considerations.rst b/doc/source/building-and-running/considerations.rst new file mode 100644 index 00000000..66359c89 --- /dev/null +++ b/doc/source/building-and-running/considerations.rst @@ -0,0 +1,35 @@ +Considerations +============== + +Depending on your use case, there are two main things that you need to consider: + +Do I need NetCDF? +----------------- + +`NetCDF `_ is a data format (and associated software libraries) specifically designed for large-scale scientific data. It has two major benefits over raw binary data: + +1. It is machine-independent, so `endianness `_ is not an issue when moving datasets between machines +2. It is self-describing, so as well as containing raw data, NetCDF files also contain metadata describing the data (e.g. variable names, units, origin). Many tools are capable of exploiting this metadata to simplify processing. + +JULES can be built with or without NetCDF, however *building JULES without NetCDF limits the functionality of JULES*. Without NetCDF, JULES will use a dummy NetCDF library which allows the program to build but provides no functionality. Any attempt to use NetCDF files as input with this option will result in a runtime error. All input files must be columnar ASCII, meaning that the user is restricted to running at a single point only. Output files will automatically use a columnar ASCII format with headers. File formats are discussed in more detail in :doc:`/input/overview`. + + +Do I need parallel processing? +------------------------------ + +.. note:: + For running JULES at a single point, parallel processing provides no advantage. However, if JULES is already compiled with OpenMP or MPI enabled, it is still possible to run a single point by simply specifying the number of OpenMP threads and/or MPI tasks to be 1. + +JULES is capable of exploiting parallel processing techniques to reduce processing time for distributed/gridded simulations. There are two different methods JULES can use: + +OpenMP + `OpenMP `_ is a form of compiler-assisted parallelisation that uses directives for shared-memory, loop-level parallelism across multiple cores on a machine (OpenMP is *not* capable of utilising a cluster of machines). + + This form of parallelism is not as effective as MPI, but may provide some speedup and does not require a specially compiled NetCDF library. + +MPI + `MPI (Message Passing Interface) `_ is a standardised message passing interface. MPI coordinates the running of multiple 'tasks' in parallel, potentially on several machines (or nodes), and provides mechanisms for these tasks to communicate with each other. + + JULES takes advantage of the parallel I/O features available in `HDF5 `_ and `NetCDF4 `_, which enable multiple MPI tasks to read from and write to the same NetCDF file(s) at the same time. These features must be explicitly enabled when NetCDF is compiled (see :doc:`required-software`). + +It is also possible to use MPI and OpenMP together, where each MPI task has a number of OpenMP threads, however this is very advanced and beyond the scope of this document. diff --git a/doc/source/building-and-running/fcm.rst b/doc/source/building-and-running/fcm.rst new file mode 100644 index 00000000..0b6d9bd9 --- /dev/null +++ b/doc/source/building-and-running/fcm.rst @@ -0,0 +1,253 @@ +Building JULES using FCM +======================== + +FCM is a code management and build system developed by the Met Office with a particular focus on simplifying the process of building large Fortran programs. In this section, we will be using the build tool - FCM make. + +As part of the build process, FCM make will analyse the dependencies of every Fortran file and automatically compile them in the correct order. + +FCM make must be given a configuration file that it uses to determine how to build the source code. Extensive documentation on FCM make configuration files is `available online `_. + +Help pages for the FCM make command itself (rather than the configuration file) can be accessed using the command: + +.. code-block:: bash + + fcm help make + +The FCM configuration file for building JULES is ``etc/fcm-make/make.cfg``. This file uses the environment variables below to determine the settings to use when compiling JULES. + +Running FCM make with this configuration file will create some files and directories in the specified build directory (see the ``-C`` option of ``fcm make``; defaults to the current working directory). The JULES executable will be produced in the specified build directory at ``build/bin/jules.exe``. + + +.. _fcm-make-environment-variables: + +Environment variables used when building JULES using FCM make +------------------------------------------------------------- + +``JULES_PLATFORM`` + Used to select settings for a pre-defined platform. The default values of other variables may depend on the choice of this setting; differences from the generic defaults are included in the descriptions below. + + .. note:: + If you have many users using the same platform to run JULES, you may want to contribute a suitable platform configuration. + + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Permitted value | Purpose | + +============================+==============================================================================================================================================================+ + | ``custom`` | **Default.** Use a custom configuration entirely determined by the other environment | + | | variables. The default values of those variables are set in this platform's configuration file. | + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``vm`` | Use settings for the `JULES development virtual machine`. | + | | | + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``ceh`` | Use settings for the GFortran compiler on the CEH Linux systems. | + | | | + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``jasmin-lotus-intel`` | Use settings for the Intel compiler on the Lotus system at JASMIN. | + | | | + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``jasmin-gcc-nompi`` | Use settings for the gfortran compiler on the JASMIN Cylc server. | + | | | + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``jasmin-intel-nompi`` | Use settings for the intel compiler on the JASMIN Cylc server. | + | | | + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``meto-linux-gfortran`` | Use settings for the GFortran compiler on Met Office Linux systems. | + | | | + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``meto-linux-nagfor`` | Use settings for the NAG compiler on Met Office Linux systems. | + | | | + | | **Warning:** This build configuration is intended for correctness checking only, not production runs. | + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``meto-linux-intel-nompi`` | Use settings for the Intel compiler *without* MPI on Met Office Linux systems. | + | | | + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``meto-linux-intel-mpi`` | Use settings for the Intel compiler *with* MPI on Met Office Linux systems. | + | | | + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``meto-xc40-cce`` | Use settings for the Cray Compiler Environment on the Met Office Cray XC40 system. | + | | | + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``uoe-linux-gfortran`` | Use settings for the GFortran compiler on University of Exeter Linux system (SL7). | + | | | + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +``JULES_REMOTE``, ``JULES_REMOTE_HOST``, ``JULES_REMOTE_PATH`` + .. warning:: Advanced users only + + Used to determine whether the build will happen on a local or remote machine. + + +-----------------+----------------------------------------------------------------------------------+ + | Permitted value | Purpose | + +=================+==================================================================================+ + | ``local`` | **Default.** All compilation occurs on the local machine. | + +-----------------+----------------------------------------------------------------------------------+ + | ``remote`` | Code is extracted on the local machine and mirrored to | + | | ``${JULES_REMOTE_HOST}@${JULES_REMOTE_PATH}``, where ``JULES_REMOTE_HOST`` is | + | | the name of the remote machine and ``JULES_REMOTE_PATH`` is the path on the | + | | remote machine. | + | | | + | | The compilation can then be completed on the remote machine. See below for an | + | | example. | + +-----------------+----------------------------------------------------------------------------------+ + +``JULES_COMPILER`` + Used to select compiler specific settings. + + +-----------------+----------------------------------------------------------------------------------+ + | Permitted value | Purpose | + +=================+==================================================================================+ + | ``gfortran`` | **Default.** Use settings for the `GNU Fortran compiler`_. | + +-----------------+----------------------------------------------------------------------------------+ + | ``intel`` | Use settings for the `Intel Fortran compiler`_. | + +-----------------+----------------------------------------------------------------------------------+ + | ``nagfor`` | Use settings for the `NAG Fortran compiler`_. | + +-----------------+----------------------------------------------------------------------------------+ + | ``cray`` | Use settings for the `Cray Compiler Environment`_. | + +-----------------+----------------------------------------------------------------------------------+ + +``JULES_BUILD`` + Used to select the type of build. + + +-----------------+----------------------------------------------------------------------------------+ + | Permitted value | Purpose | + +=================+==================================================================================+ + | ``normal`` | **Default.** Compile JULES normally. | + +-----------------+----------------------------------------------------------------------------------+ + | ``debug`` | Compile JULES with additional settings for debugging. | + +-----------------+----------------------------------------------------------------------------------+ + | ``fast`` | Compile JULES with additional settings for faster execution. | + +-----------------+----------------------------------------------------------------------------------+ + +``JULES_OMP`` + Used to determine whether to build with OpenMP or not. + + +-----------------+----------------------------------------------------------------------------------+ + | Permitted value | Purpose | + +=================+==================================================================================+ + | ``noomp`` | **Default.** Compile JULES with OpenMP off. | + +-----------------+----------------------------------------------------------------------------------+ + | ``omp`` | Compile JULES with OpenMP on. | + +-----------------+----------------------------------------------------------------------------------+ + +``JULES_MPI`` + Used to determine whether to build with MPI enabled or not. + + +-----------------+----------------------------------------------------------------------------------+ + | Permitted value | Purpose | + +=================+==================================================================================+ + | ``nompi`` | **Default.** Compile JULES without MPI support. | + +-----------------+----------------------------------------------------------------------------------+ + | ``mpi`` | Compile JULES with MPI support. | + +-----------------+----------------------------------------------------------------------------------+ + +``JULES_NETCDF`` + Indicates whether to use a dummy NetCDF library or a 'real' NetCDF library. + + +-----------------+----------------------------------------------------------------------------------+ + | Permitted value | Purpose | + +=================+==================================================================================+ + | ``nonetcdf`` | **Default.** Use a dummy NetCDF library. | + +-----------------+----------------------------------------------------------------------------------+ + | ``netcdf`` | Use a 'real' NetCDF library. | + | | | + | | The NetCDF installation to use is specified using one of: | + | | | + | | * ``JULES_NETCDF_PATH`` | + | | * ``JULES_NETCDF_INC_PATH`` and ``JULES_NETCDF_LIB_PATH`` | + +-----------------+----------------------------------------------------------------------------------+ + +``JULES_NETCDF_PATH`` + Path to NetCDF installation. + + This sets ``JULES_NETCDF_INC_PATH = $JULES_NETCDF_PATH/include`` and ``JULES_NETCDF_LIB_PATH = $JULES_NETCDF_PATH/lib``. These can be overridden by setting the variables directly. + +``JULES_NETCDF_INC_PATH`` + Path to NetCDF include directory (i.e. directory containing ``netcdf.mod``). + +``JULES_NETCDF_LIB_PATH`` + Path to NetCDF library directory (i.e. directory containing ``libnetcdff.a`` and ``libnetcdf.a``). + +.. note:: + When compiled in parallel mode, NetCDF must be statically linked. This means the compiler must be able to find all required library and include files (i.e. for NetCDF, HDF5, curl and zlib) in ``JULES_NETCDF_INC_PATH``, ``JULES_NETCDF_LIB_PATH`` or the default search path. + +``JULES_FFLAGS_EXTRA`` + Any additional compiler flags you wish to add to the build. For example, to activate additional compiler checks. + +``JULES_LDFLAGS_EXTRA`` + Any additional library flags you wish to add to the build. This may need to include both the linker flags themselves and, if you are linking in a new library, the flags specifying the path to the new library object. + +.. note:: + When adding a completely new external dependency it is likely you will need to edit or override the FCM make build configuration files. The FCM make tool performs a dependency analysis on the JULES source tree to ensure all of the required files are present. Any new external sources must be added to the list of exclusions from this analysis or the build will fail when the external files cannot be found in the JULES working copy. + +``JULES_SOURCE`` + The full path to the copy of JULES being compiled. This could be a directory path or an FCM/Subversion/file URL to a repository location. This variable is used by the configuration file contained in many Rose fcm_make apps, but is not read by JULES itself. + + +Example FCM make commands +------------------------- + +To create a normal JULES executable without NetCDF using the GFortran compiler (taking advantage of the default values for the environment variables): + +.. code-block:: bash + + $ fcm make -j 2 -f etc/fcm-make/make.cfg --new + +To create a fast JULES executable with NetCDF using the Intel compiler: + +.. code-block:: bash + + $ export JULES_COMPILER=intel + $ export JULES_BUILD=fast + $ export JULES_NETCDF=netcdf + $ export JULES_NETCDF_PATH=/path/to/netcdf # Replace this with the correct path + $ fcm make -j 2 -f etc/fcm-make/make.cfg --new + +To create a fast JULES executable with NetCDF using the GFortran compiler on a Met Office Linux system (making use of the platform setting): + +.. code-block:: bash + + $ export JULES_PLATFORM=meto-linux-gfortran + $ export JULES_BUILD=fast + $ export JULES_NETCDF=netcdf # Note that we don't need to specify paths + $ fcm make -j 2 -f etc/fcm-make/make.cfg --new + +To create a normal JULES executable with NetCDF and OpenMP using the Intel compiler on a remote machine: + +.. code-block:: bash + + localhost $ export JULES_REMOTE=remote + localhost $ export JULES_REMOTE_HOST=my-host + localhost $ export JULES_REMOTE_PATH=/path/on/remote/host + localhost $ export JULES_COMPILER=intel + localhost $ export JULES_OMP=omp + localhost $ export JULES_NETCDF=netcdf + localhost $ export JULES_NETCDF_PATH=/path/to/netcdf # Replace this with the path ON THE REMOTE MACHINE + localhost $ fcm make -f etc/fcm-make/make.cfg --new # This does the extract and mirror steps + localhost $ ssh -Y my-host + my-host $ cd /path/on/remote/host + my-host $ fcm make -j 4 --new # This does the preprocess and build steps + +To create a normal JULES executable with MPI enabled, using the Intel compiler with array bounds checking turned on: + +.. code-block:: bash + + $ export JULES_COMPILER=intel + $ export JULES_MPI=mpi + $ export JULES_NETCDF=netcdf # We have to use NetCDF for distributed simulations + $ export JULES_NETCDF_PATH=/path/to/parallel/netcdf # NetCDF must be compiled with parallel I/O enabled + $ export JULES_FFLAGS_EXTRA="-check bounds" # Must be quoted because of the space + $ fcm make -j 2 -f etc/fcm-make/make.cfg --new + + +Tips for effective use of FCM make +---------------------------------- + +* To check the current values of the environment variables JULES will use to build, use the command ``env | grep JULES`` + +* If you always use the same compilation options for JULES, consider adding the export lines to the ``.profile`` file in your ``$HOME`` directory. Commands in the ``.profile`` file are automatically executed in any shell that you open, so defining environment variables there ensures your build environment remains consistent across shells and restarts of your computer. The definitions can still be overridden on the command line if required. + + +.. _JULES development virtual machine: https://code.metoffice.gov.uk/trac/jules/wiki/JULESVirtualMachine +.. _GNU Fortran compiler: https://www.gnu.org/software/gcc/fortran/ +.. _Intel Fortran compiler: http://software.intel.com/en-us/articles/fortran-compilers/ +.. _NAG Fortran compiler: https://www.nag.co.uk/nag-compiler +.. _Cray Compiler Environment: http://docs.cray.com/cgi-bin/craydoc.cgi?mode=SiteMap;f=xc_sitemap diff --git a/doc/source/building-and-running/intro.rst b/doc/source/building-and-running/intro.rst new file mode 100644 index 00000000..4ab3fc43 --- /dev/null +++ b/doc/source/building-and-running/intro.rst @@ -0,0 +1,17 @@ +========================== +Building and running JULES +========================== + + +This section details the options available for compiling and running JULES. + + +.. toctree:: + :maxdepth: 2 + + considerations + required-software + fcm + running-jules + rose + diff --git a/doc/source/building-and-running/required-software.rst b/doc/source/building-and-running/required-software.rst new file mode 100644 index 00000000..c9c6715d --- /dev/null +++ b/doc/source/building-and-running/required-software.rst @@ -0,0 +1,37 @@ +Required software +================= + +Building a JULES executable requires FCM and one of the supported Fortran compilers (see :doc:`fcm`). The Fortran 90 NetCDF interface library is required to use gridded data (i.e. data for more than a single location). + +To be able to automatically upgrade namelists between JULES versions or use a GUI to configure JULES runs, Rose is required. + +All of this software is freely available: + +* GFortran, the GNU GCC Fortran compiler - https://www.gnu.org/software/gcc/fortran +* FCM - http://metomi.github.io/fcm/doc +* Rose - http://metomi.github.io/rose/doc/html/index.html +* NetCDF libraries - http://www.unidata.ucar.edu/software/netcdf + +JULES has only been tested on Linux but, given a suitable Fortran compiler, should run on any Unix-like system with minimal changes. The recommended way to attempt to run JULES on Windows is via the Linux compatability layer `Cygwin `_, although this is untested. + + +Building JULES with NetCDF +-------------------------- + +To build JULES with NetCDF, it must be told where to find the NetCDF library files. JULES needs two pieces of information - the directory containing the NetCDF archive files, ``netcdf.a`` and ``netcdff.a`` (the *'NetCDF library path'*), and the directory containing the NetCDF Fortran 90 module file, ``netcdf.mod`` (the *'NetCDF include path'*). In a standard NetCDF install, these are often ``/usr/lib`` and ``/usr/include`` or ``/usr/local/lib`` and ``/usr/local/include`` respectively. + +If the ``nc-config`` program is installed on your system (run ``which nc-config`` to find out), this can be used to determine values for the NetCDF library path (``nc-config --flibs``) and NetCDF include path (``nc-config --includedir``). When JULES is built with NetCDF, users can supply either ASCII or NetCDF input files, and all output will be NetCDF. + + +Building and running JULES with MPI +----------------------------------- + +.. warning:: For advanced users only + +In order to build and run JULES with MPI, additional software is required: + +#. An implementation of MPI compiled using the same compiler you will be using to compile JULES. Several implementations of MPI are available, the most commonly used being `MPICH2 `_ and `OpenMPI `_. + + .. note:: The ``bin`` directory of your MPI installation must be in your ``$PATH`` + +#. A version of HDF5/NetCDF4 compiled *with parallel I/O enabled*, using the MPI implementation installed above. This is *not* the default way to compile NetCDF, and must be explicitly enabled. More information on how to do this can be found on the `NetCDF website `_. diff --git a/doc/source/building-and-running/rose.rst b/doc/source/building-and-running/rose.rst new file mode 100644 index 00000000..ec4bb132 --- /dev/null +++ b/doc/source/building-and-running/rose.rst @@ -0,0 +1,133 @@ +Automatic upgrading and GUI using Rose +====================================== + +`Rose `_ is a collection of tools for managing the building and running of scientific applications. + +.. seealso:: + Please familiarise yourself with the `Rose documentation `_ before continuing with this section. + +.. note:: + This section assumes `Rose is installed `_. + + We will not be using Rose Bush or Rosie, so those components need not be installed. + + It is not necessary to install Cylc, but some functionality will not be available. This will be noted as we go. + +JULES uses Rose primarily to provide a graphical interface for configuring and running JULES, but also to allow automatic upgrading of JULES runs from one version to the next. + +A Rose suite for JULES will normally contain two applications - an ``fcm_make`` application for building JULES and a ``jules`` application for configuring the namelists and running JULES. + + +Creating a Rose suite from existing namelists +--------------------------------------------- + +To enable users to quickly transition to Rose and the extra functionality it provides, a tool is distributed with JULES that can convert existing namelists to a Rose suite. + +To convert vn3.4 namelists to a vn4.7 Rose suite, run the following command in the directory containing the namelists: + +.. code-block:: bash + + create_rose_app vn3.4 vn4.7 namelist_path suite_name jules_dir + +Where ``jules_dir`` is the path to the root directory of the most recent JULES code release on your machine. + +The ``namelist_path`` can be the full or a relative path. + +This will create a directory called ``suite_name`` in ~/roses/ directory which contains a fully functional Rose suite. + +To convert namelists to a Rose suite without upgrading the version, just give the same version for both. + + +Using Rose to upgrade existing namelists +---------------------------------------- + +It is not necessary to use Rose to configure and run JULES - Rose can be used just to upgrade existing namelists (at vn3.4 or later). + +In order to use Rose to upgrade existing namelists from vn3.4 to vn4.0, just execute the following commands in the directory containing your namelists: + +.. code-block:: bash + + # Creates a Rose suite at rose-suite + $JULES_ROOT/bin/create_rose_app vn3.4 vn4.0 + + # Remove the current namelists + rm -rf *.nml + + # Use Rose to generate the new namelists + rose app-run -i -C rose-suite/app/jules + + # Remove the Rose suite and other generated files + rm -rf rose-suite .rose-config_processors-file.db rose-app-run.conf + + +Upgrading an existing JULES Rose suite +-------------------------------------- + +Upgrading an existing JULES Rose suite is even more simple than upgrading the namelist files directly. To see the versions it is possible to upgrade to, run the command: + +.. code-block:: bash + + rose app-upgrade -M $JULES_ROOT/rose-meta -C /path/to/rose/suite/app/jules --all-versions + && rose macro --fix -C app/jules + + rose app-upgrade -M $JULES_ROOT/rose-meta -C /path/to/rose/suite/app/fcm_make --all-versions + && rose macro --fix -C app/fcm_make + +To then upgrade to one of those versions, the command is: + +.. code-block:: bash + + rose app-upgrade -M $JULES_ROOT/rose-meta -C /path/to/rose/suite/app/jules + && rose macro --fix -C app/jules + + rose app-upgrade -M $JULES_ROOT/rose-meta -C /path/to/rose/suite/app/fcm_make + && rose macro --fix -C app/fcm_make + + +Configuring JULES with a graphical interface +-------------------------------------------- + +Using a Rose suite to run JULES has the advantage that it can be configured graphically using `Rose Config Edit `_. + +To launch the graphical editor, the following command is used: + +.. code-block:: bash + + # To edit the whole suite, including build configuration + rose config-edit -M $JULES_ROOT/rose-meta -C /path/to/rose/suite & + + # To edit just the namelists + rose config-edit -M $JULES_ROOT/rose-meta -C /path/to/rose/suite/app/jules & + +where ``$JULES_ROOT`` is the root directory of your JULES installation. For more information on using the config editor, see `the Rose documentation `_ + +Clicking on a variable name in the editor opens the corresponding page in this documentation. + + +Running a JULES Rose suite +-------------------------- + +Without Cylc +^^^^^^^^^^^^ + +To run JULES from a Rose suite without Cylc, we just use Rose to generate the namelists. JULES is then built and run as normal - see :doc:`intro`. + +To generate namelists in the current directory from a Rose suite at ``/path/to/rose/suite``, use the following command: + +.. code-block:: bash + + rose app-run -i -C /path/to/rose/suite/app/jules + + +With Cylc +^^^^^^^^^ + +.. warning:: This requires Cylc to be installed and configured. + +Once a JULES Rose suite has been suitably configured using the graphical editor, it can be run using the following command: + +.. code-block:: bash + + rose suite-run -C /path/to/rose/suite + +This will set the suite running, and will launch the `Cylc `_ GUI to allow you to see the status of your suite as it runs. The GUI also allows you to view log files etc. - these can be useful when a job fails! diff --git a/doc/source/building-and-running/running-jules.rst b/doc/source/building-and-running/running-jules.rst new file mode 100644 index 00000000..bae66258 --- /dev/null +++ b/doc/source/building-and-running/running-jules.rst @@ -0,0 +1,82 @@ +Running JULES +============= + +The user interface of JULES consists of several files with the extension ``.nml`` containing Fortran namelists. These files and the namelist members are documented in more detail in :doc:`/namelists/contents`. These namelists are grouped together in a single directory. That directory is referred to as the *namelist directory* for a JULES run. In most use cases, this is practically abstracted away by the use of the rose/cylc workflow. This provides a GUI and rich ecosystem for integration of JULES into a larger workflow (eg compile-run-analyse). + +Once a :doc:`JULES executable is compiled ` and the :doc:`namelists ` are set up, JULES can be run in one of two ways: + +1. Run the JULES executable in the namelist directory with no arguments: + + .. code-block:: bash + + cd /path/to/namelist/dir + /path/to/jules.exe + +2. Run the JULES executable with the namelist directory as an argument: + + .. code-block:: bash + + /path/to/jules.exe /path/to/namelist/dir + + +.. warning:: + Any relative paths given to JULES via the namelists (e.g. :nml:mem:`JULES_FRAC::file` in :nml:lst:`JULES_FRAC`) will be interpreted *relative to the current working directory*. + + This means that if the user plans to use the second method to run JULES (e.g. in a batch environment), it is advisable to use fully-qualified path names for all files specified in the namelists. + + To allow runs to be portable across different machines, it is common to specify data files relative to the namelist directory. In this case, JULES must be run using the first method to allow the relative paths to be resolved correctly. + + +General example of running JULES from the command line +--------------------------------------------------------- + +#. Move into the JULES root directory (the directory containing ``includes``, ``src`` etc.): + + .. code-block:: bash + + $ cd /jules/root/dir + +#. Build JULES: + + .. code-block:: bash + + $ fcm make -f etc/fcm-make/make.cfg + +#. Move into the namelist directory: + + .. code-block:: bash + + $ cd /path/to/namelist/dir + +#. Run the JULES executable: + + .. code-block:: bash + + $ /path/to/jules.exe + + +Running JULES with OpenMP +------------------------- + +If JULES is compiled with OpenMP, then it must be told how many OpenMP threads to use. This is done using the environment variable ``OMP_NUM_THREADS``: + +.. code-block:: bash + + $ export OMP_NUM_THREADS=4 # Use 4 threads for OpenMP parallel regions + $ /path/to/jules.exe + + +Running JULES with MPI +---------------------- + +When running JULES using MPI, JULES attempts to find a suitable decomposition of the grid depending on how many MPI tasks are made available to it. Each MPI task can then be thought of as its own independent version of JULES, with each task being responsible for a portion of the grid. Each task reads its portion of the input file(s), performs calculations on those points and outputs its portion of the output file(s). Tasks only communicate in order to read and write dump files - this ensures that dump files are consistent regardless of decomposition, i.e. a dump from any run (MPI or not; different numbers of MPI tasks), can be used to (re-)start any other run and produce identical results, providing the overall model grids are the same. + +None of the namelists or namelist members are parallel-specific - the same :doc:`JULES namelists ` can be used to run JULES with or without MPI, and the final results will be identical. + +If JULES is compiled with MPI, then it must be run using commands from your MPI distribution (usually called ``mpiexec`` and/or ``mpirun``): + +.. code-block:: bash + + $ mpirun -n 4 /path/to/jules.exe # Run JULES using 4 MPI tasks + +Detailed discussion of ``mpiexec``/``mpirun`` is beyond the scope of this document - please refer to the documentation for your chosen MPI distribution for the available options and features. diff --git a/doc/source/code/contents.rst b/doc/source/code/contents.rst new file mode 100644 index 00000000..f5f88aca --- /dev/null +++ b/doc/source/code/contents.rst @@ -0,0 +1,8 @@ +=================== +Aspects of the code +=================== + + +.. toctree:: + io + known-limitations \ No newline at end of file diff --git a/doc/source/code/io.rst b/doc/source/code/io.rst new file mode 100644 index 00000000..af417ae4 --- /dev/null +++ b/doc/source/code/io.rst @@ -0,0 +1,194 @@ +I/O framework +============= + + +JULES version 3.1 saw a complete rewrite of the I/O code to use a more modular and flexible structure. This section attempts to give a brief description of the low-level I/O framework, and explains how to make some commonly required changes. + +.. warning:: This section requires a good knowledge of Fortran. + + +Overview +-------- + +The JULES I/O code is comprised of several 'layers' with clearly defined responsibilities that communicate with each other, as shown in the figure :ref:`figure-modular-structure` (the relevant Fortran modules for each layer are also given). The blocks in orange are the JULES specific pieces of code - in theory, the rest of the code could be used with other models if different implementations of these modules were provided. + +.. _figure-modular-structure: + +.. figure:: io_modular_structure.png + :alt: Modular structure of the JULES I/O code + + Modular structure of the JULES I/O code + +The core component in the I/O framework is the common file handling API. This layer provides a common interface for different file formats that is then used by the rest of the code. The drivers for ASCII and NetCDF files implement this interface. The interface is based around the concepts of dimensions and variables, much like NetCDF (except that nothing is inferred from metadata - all information about variables and dimensions must be prescribed), but adds the concept of a "record" to that: + +Dimension + A file has one or more dimensions. Each regular dimension has a name and a size. + + One dimension is special, and is referred to as the record dimension. It has a name but has no defined size. A typical use of the record dimension is to represent time. + +Variable + A file has one or more variables. The size of each variable is defined using the dimensions previously defined in the file. Each variable can opt to use the record dimension or not - if a variable uses the record dimension it must be the last dimension that the variable has. + +Record + A record is the collection of all variables at a certain value of the record dimension. The figure :ref:`figure-records-in-file` gives an example of this: + + .. _figure-records-in-file: + + .. figure:: records_in_file.png + :alt: Records in a file + + Records in a file + + In the figure, each variable has dimensions x, y and n, where n is the record dimension. Each green box represents the (2D plane of) values of a variable for a certain value of n. A record is then the collection of all variables at a certain value of n. + + A good analogy is the lines in an ASCII file, where each column represents a variable and each line is a record (in fact, this is a generalisation to multiple dimensions of that exact concept). + +Files keep track of the record they are currently pointing at (it is the responsibility of the file-type drivers to do this in the way that best suits the file format they implement). When a file receives a read or write request for a particular variable, the values are read from or written to the current record. + +The record abstraction also allows two useful operations - seek and advance. When a file receives an instruction to seek to a particular record, it sets its internal pointer so that read/write requests access the given record (a use of this within JULES is looping the input files round spin-up cycles). An advance instruction just moves the internal pointer on to the next record. + +The routines in ``file_mod`` define the interface that each file-type driver must implement, and are responsible for deciding which driver to defer to. Support for a file format is provided by implementing this interface and declaring the implementation in ``file_mod``. This is discussed in further detail in :ref:`implementing-a-new-file-format`. + +The gridded file API then imposes the concept of reading and writing cubes of gridded data (i.e. x and y dimensions for the grid, plus zero or more 'levels' dimensions) on top of the common file handling API. The underlying files may have a 1D or 2D grid (see :doc:`/input/overview`), and this layer handles the grid dimensions transparently. It is this layer that handles the extraction of a subgrid from a larger grid (see ``file_gridded_read_var`` and ``file_gridded_write_var``). + +The time series file API builds on the gridded file API by explicitly presenting the record dimension as a time dimension. It provides an interface that allows users to treat multiple files (e.g. monthly files, yearly files) as if they were a single file (i.e. seek and advance will automatically open and close files if required). + +The input and output layers interact with the model via an interface provided by ``model_interface_mod``. ``model_interface_mod`` allows the input and output layers to read values from and write values to the internal model variables. This is discussed in more detail in :ref:`implementing-new-variables-for-input-and-output`. The input and output layers use the time series file API to read from and write to file. + +This should provide a reasonable introduction to the JULES I/O framework, but looking at the code is the best way to learn about it. + + +.. _implementing-new-variables-for-input-and-output: + +Implementing new variables for input and output +----------------------------------------------- + +The only I/O code that needs to be modified to add new variables for input and output is in ``model_interface_mod`` (the routines in ``src/io/model_interface``). All interaction between the I/O code and the model happens in this module (apart from reading and writing dump files). + +Before adding any code to ``model_interface_mod``, the variable the user wishes to make available for input and/or output must be accessible to ``model_interface_mod``. This is usually accomplished by placing the variable in a module and importing the module into ``model_interface_mod`` where required, e.g.: + +.. code-block:: fortran + + ! Declare the variable in a module + MODULE my_module + + REAL, ALLOCATABLE :: my_var(:) + + ! ... + END MODULE my_module + + + ! ... Later, in model_interface_mod + USE my_module, ONLY : my_var + + +``model_interface_mod`` contains several routines: + +* Two routines that populate and extract data from the relevant model variables. These are ``populate_var`` and ``extract_var`` respectively. +* Routines that provide various pieces of information (e.g. string identifiers, number and size of 'levels' dimensions) about the available variables to the input and output layers. Internally, a metadata array that contains information about the available variables is used to implement these 'information providing' routines. + + +In most cases, the following edits will be sufficient to add a variable for input and/or output: + +``model_interface_mod.F90`` + .. note:: Required for both input and output variables. + + Increment the constant ``N_VARS``. This ``PARAMETER`` indicates how many elements are in the metadata array. If you forget to do this, the module will fail to compile. + +``populate_var.inc`` + .. note:: Required for input variables only. + + ``populate_var`` takes a variable identifier and a cube of data on the full model grid, and populates the associated model variable using that data. This is done using a ``SELECT`` statement, to which a case must be added for the new variable. + +``extract_var.inc`` + .. note:: Required for output variables only. + + ``extract_var`` takes a variable identifier, extracts the values from the associated model variable, and returns those values as a cube of data on the full model grid. This is done using a ``SELECT`` statement, to which a case must be added for the new variable. + +``variable_metadata.inc`` + .. note:: Required for both input and output variables. + + This file contains the ``DATA`` definition for the variable metadata array. The metadata array contains objects of the derived type ``var_metadata``, which is defined in ``model_interface_mod.F90``. A typical entry in this array will look something like: + + .. code-block:: fortran + + !----------------------------------------------------------------------------- + ! Metadata for latitude + !----------------------------------------------------------------------------- + DATA metadata(1) / var_metadata( & + ! String identifier + 'latitude', & + ! Variable type + VAR_TYPE_SURFACE, & + ! Long name + "Gridbox latitude", & + ! Units + "degrees" & + ) / + + This allows us to define all the static information about a variable in one place: + + String identifier + This is the name used to identify the variable in namelists (as seen elsewhere in the User Guide) + + Variable type + This indicates the number and size of the 'levels' dimensions for the variable. For a full list of types see the file ``get_var_levs_dims.inc``; some of the available types are: + + +----------------------+-----------------------------------------------------------------------------------------------------+ + | Type | Number and size of 'levels' dimension(s) | + +======================+=====================================================================================================+ + | ``VAR_TYPE_SURFACE`` | No levels dimension | + +----------------------+-----------------------------------------------------------------------------------------------------+ + | ``VAR_TYPE_PFT`` | Single levels dimension of size :nml:mem:`JULES_SURFACE_TYPES::npft` | + +----------------------+-----------------------------------------------------------------------------------------------------+ + | ``VAR_TYPE_NVG`` | Single levels dimension of size :nml:mem:`JULES_SURFACE_TYPES::nnvg` | + +----------------------+-----------------------------------------------------------------------------------------------------+ + | ``VAR_TYPE_TYPE`` | Single levels dimension of size ``ntype`` (:nml:mem:`JULES_SURFACE_TYPES::npft` + | + | | :nml:mem:`JULES_SURFACE_TYPES::nnvg`) | + +----------------------+-----------------------------------------------------------------------------------------------------+ + | ``VAR_TYPE_TILE`` | Single levels dimension of size ``nsurft`` (1 if :nml:mem:`JULES_SURFACE::l_aggregate` = TRUE, | + | | ``ntype`` otherwise) | + +----------------------+-----------------------------------------------------------------------------------------------------+ + | ``VAR_TYPE_SOIL`` | Single levels dimension of size :nml:mem:`JULES_SOIL::sm_levels` | + +----------------------+-----------------------------------------------------------------------------------------------------+ + | ``VAR_TYPE_SCPOOL`` | Single levels dimension of size ``dim_cs1`` (number of soil carbon pools, i.e. 4 if | + | | :nml:mem:`JULES_VEGETATION::l_triffid` = TRUE, 1 otherwise) | + +----------------------+-----------------------------------------------------------------------------------------------------+ + | ``VAR_TYPE_SNOW`` | Two levels dimensions: the first of size ``nsurft`` and the second of size | + | | :nml:mem:`JULES_SNOW::nsmax` | + +----------------------+-----------------------------------------------------------------------------------------------------+ + + Adding a new type is a relatively simple procedure: + + #. A new ``PARAMETER`` must be added for the type in ``model_interface_mod.F90`` + #. A new ``CASE`` must be added to the ``SELECT`` statement in ``get_var_levs_dims.inc`` that correctly returns the number, names and sizes of the levels dimensions. + + Long name + This is the name used in the ``long_name`` attribute for the variable in output files. + + Units + This is the units given in the ``units`` attribute for the variable in output files. + + +``map_from_land`` and ``map_to_land`` are provided as utilities for use with variables that are defined on land points only. ``tiles_to_gbm`` is used to provide gridbox mean diagnostics for model variables that have one value per surface tile. + +As always, the best way to go about implementing new variables for input and output is to follow the examples that are already there. + + +.. _implementing-a-new-file-format: + +Implementing a new file format +------------------------------ + +To understand how to implement a new file format, it first helps to understand how the common file handling layer works under the hood. + +Each of the routines in ``file_mod`` (see files in ``src/io/file_handling/core``) takes a ``file_handle`` as its first argument. The ``file_handle`` is a Fortran derived type that contains a flag indicating the format of the file it represents, and each of the routines in ``file_mod`` contains a ``SELECT`` statement that defers to the correct implementation of the routine based on that flag. + +``file_handles`` are created in ``file_open``. Each file format implementation defines a list of recognised file extensions, and the appropriate file opening routine is deferred to by comparing the extension of the given file name to the recognised extensions for each file format. + +To implement a new file format, an implementation of each of the routines in ``file_mod`` must first be provided (the implementations for ASCII and NetCDF formats should be used as a reference). A new ``CASE`` deferring to the new implementation should then be added to the ``SELECT`` statement in each of the routines in ``file_mod``. The recognised file extensions for the new format should also be added to the checks in ``file_open`` to allow the new the file opening routine to be called. + +Implementations of these routines for ASCII and NetCDF file formats are given in ``driver_ascii`` (see ``src/io/file_handling/core/drivers/ascii``) and ``driver_ncdf`` (see ``src/io/file_handling/core/drivers/ncdf``) respectively. These should be used as examples of how to implement a file format. + +These two file formats suffer from opposite problems when implementing the concepts of dimensions, variables and records. For NetCDF, the concepts of dimensions and variables already exist, but the idea of a record has to be imposed. For ASCII, the concept of a record is a natural fit (think lines in a file), but the concepts of dimensions and variables have to be imposed. Between them, these implementations should provide sufficient examples of how to implement a new file format. + diff --git a/doc/source/code/io_modular_structure.png b/doc/source/code/io_modular_structure.png new file mode 100644 index 0000000000000000000000000000000000000000..f973ad555e244c1ac556941cbb3369c688341ee1 GIT binary patch literal 24670 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 NP9AeQiaQdR`cHBs3q$|_ literal 0 HcmV?d00001 diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..f7850c8e --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,287 @@ +# -*- coding: utf-8 -*- +# +# Joint UK Land Environment Simulator (JULES) User Guide build configuration file, created by +# sphinx-quickstart on Thu Mar 21 11:40:02 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# Add the sphinxext directory to the Python search path +# Remember that when this script is executed, the current working directory is the directory containing this file +sys.path.insert(0, os.path.abspath('../sphinxext')) + + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + # Sphinx extensions + 'sphinx.ext.todo', 'sphinx.ext.imgmath', 'sphinx.ext.mathjax', + # Custom extensions + 'sphinx_nml_domain', 'pygments_fortran_nml_lexer', 'pygments_fcm_make_conf_lexer' +] + +# Use nitpicky mode so that bad cross-references are flagged +nitpicky = True + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Joint UK Land Environment Simulator (JULES)' +copyright = u'2025' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '7.9' +# The full version, including alpha/beta/rc tags. +release = '7.9' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +highlight_language = 'nml' + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'nature' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = "%s v%s User Guide" % (project, version) + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = "jules_logo_html.png" + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add extra CSS files here to remove the need for a layout.html +# template override file +html_css_files = [ + 'jules-tweaks.css', +] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'JULES_User_Guide' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). + 'papersize': 'a4paper', + +# The font size ('10pt', '11pt' or '12pt'). + 'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. + 'fontenc' : '\\usepackage[LGR,T1]{fontenc}', + +# Remove the blank pages that result from formatting for double sided printing + 'classoptions': ',openany,oneside', + 'babel' : '\\usepackage[english]{babel}' +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'JULES_User_Guide.tex', u'Joint UK Land Environment Simulator (JULES) User Guide', + u'Met Office', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +latex_logo = "jules_logo_pdf.png" + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'JULES_User_Guide', u'Joint UK Land Environment Simulator (JULES) User Guide', + [u'Met Office'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'JULES_User_Guide', u'Joint UK Land Environment Simulator (JULES) User Guide', + u'Met Office', 'JULES', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# Linkcheck options +# Initially, ignore all broken links +linkcheck_ignore = [ + r"https?://code.metoffice.gov.uk/.*", + r"https?://www.nag.co.uk/nag-compiler", + r"https?://doi.org/10.3354/cr00899", + r"https?://puma.nerc.ac.uk/trac/JULES", + r"https?://doi.org/10.1007/BF0038623", + r"https?://docs.cray.com/.*", + r"https?://cylc.github.io/cylc/", + r"https?://jules.jchmr.org/content/.*", + r"https?://nora.nerc.ac.uk/10890/1/dadson_etal_2010_g2gtrip.pdf", + r"https?://www.borenv.net/BER/pdfs/ber15/ber15-501.pdf", + r"https?://www.unidata.ucar.edu/software/netcdf/docs/.*", + r"https?://.*wiley.com/.*", + r"https?://www.liebertpub.com/.*", + r"https?://royalsocietypublishing.org/.*", + r"https?://www.gnu.org/.*", + r"https?://software.intel.com/.*", + ] + +# Bump the limit up a bit +linkcheck_retries = 3 + diff --git a/doc/source/examples.rst b/doc/source/examples.rst new file mode 100644 index 00000000..69b7ca9a --- /dev/null +++ b/doc/source/examples.rst @@ -0,0 +1,8 @@ +JULES examples +============== + + +If you are using a version of JULES since vn5.0, please see the list of standard jobs in the table given `here `__ or the +'Example configurations' row of the table `here `__. + +For earlier versions, please see chapter 8 of the appropriate `JULES User Guide `__. diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..6709c715 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,31 @@ +.. JULES (Joint UK Land Environment Simulator) documentation master file, created by + sphinx-quickstart on Thu Mar 21 11:40:02 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +====================================================== +Joint UK Land Environment Simulator (JULES) User Guide +====================================================== + + +The Joint UK Land Environment Simulator (JULES) is a computer model that simulates many soil and vegetation processes. This guide primarily describes the format of the input and output files, and does not include detailed descriptions of the science and representation of the processes in the model. + +The first version of JULES was based on the Met Office Surface Exchange System (MOSES), the land surface model used in the `Unified Model `_ (UM) of the `UK Met Office `_. After that initial split, the MOSES and JULES code bases evolved separately, but with JULES v2.1 these differences were reconciled with the UM. As of JULES v3.1, a single code repository is used for both standalone JULES and JULES in the UM. + +Further information can be found on the JULES website: http://jules.jchmr.org/. + + +.. toctree:: + :maxdepth: 1 + :numbered: + + release_notes/contents + overview/intro + building-and-running/intro + input/overview + output + namelists/contents + examples + code/contents + output-variables + diff --git a/doc/source/input/ascii.rst b/doc/source/input/ascii.rst new file mode 100644 index 00000000..2747b358 --- /dev/null +++ b/doc/source/input/ascii.rst @@ -0,0 +1,52 @@ +ASCII files +=========== + +JULES only supports the use of ASCII files for data at a single location. In this case, the input grid can be specified either as a 1D grid with length 1 or as a 2D grid of size 1 x 1. The data should be laid out in columns with one timestep of data per row (with time increasing with the number of rows). For variables with additional 'levels' dimensions (e.g. soil layers), the values for each level should be in consecutive columns. + +.. note:: Variables should be given to JULES in the order they appear in the file, and there should be no unused variables in between. This may mean that some datasets may require pre-processing for use with JULES, even if they are already columnar. + +If the first character of a line is either ``#`` or ``!``, the line is taken to be a comment. JULES reads no information from comments - they are purely for annotating the dataset for users. + +Example ASCII input +------------------- + +ASCII meteorological forcing data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + # Meteorological data for Loobos, 1997. + # One year of 30 minute data. + # Down Down Rainfall Snowfall Air Wind Specific + # SWR LWR rate rate temp. speed Pressure humidity + #(W m-2) (W m-2) (kg m-2 s-1) (kg m-2 s-1) (K) (m s-1) ) (Pa) (kg kg-1) + 0.0 187.8 0.000E+00 0.000E+00 259.800 2.017 102400.0 1.384E-03 + 0.0 186.9 0.000E+00 0.000E+00 259.700 3.770 102400.0 1.384E-03 + 0.0 186.7 0.000E+00 0.000E+00 259.600 4.290 102400.0 1.373E-03 + # ... + +Each row represents a timestep of data. Each column represents a variable. Driving variables have no additional dimension. + +Initial conditions +~~~~~~~~~~~~~~~~~~ + +:: + + # sthuf(1:sm_levels) t_soil(1:sm_levels) + 0.749 0.743 0.754 0.759 276.78 277.46 278.99 282.48 + +Although only one 'timestep' of data is supplied, the data must still be laid out in columns. These variables have a value for each soil layer, which are given in consecutive columns. This quickly becomes cumbersome for large numbers of variables, which is why NetCDF is recommended even +for data at a single point. + +Time varying data with an additional dimension +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + # lai(1:npft) canht(1:npft) + 0.0 0.0 0.2 0.0 0.0 0.0 0.0 0.6 0.0 0.0 + 0.0 0.0 0.2 0.0 0.0 0.0 0.0 0.6 0.0 0.0 + 0.0 0.0 0.2 0.0 0.0 0.0 0.0 0.7 0.0 0.0 + # ... + +These variables have one value for each plant functional type (see :doc:`/overview/intro`). For each variable, the values for each pft are in consecutive columns. Each row is one timestep of data. diff --git a/doc/source/input/file-name-templating.rst b/doc/source/input/file-name-templating.rst new file mode 100644 index 00000000..ca09b57e --- /dev/null +++ b/doc/source/input/file-name-templating.rst @@ -0,0 +1,136 @@ +File name templating +==================== + +If the names of input files follow particular patterns, JULES can use a substitution template rather than requiring a potentially long list of file names. Templating comes in two forms, time templating and variable name templating, which can be used separately or together. + +Substitution strings are 3-character strings, starting with ``%``. JULES will automatically detect the use of either form of templating by checking for the presence of the substitution strings in file names. + + +Time templating +--------------- + +If any of the time templating substitution strings are present in a file name, then JULES assumes time-templating is to be used. The valid substitution strings for time templating are: + ++-----------------------+------------------------------------------------------------------------------------------------+ +| Substitution string | Replaced with | ++=======================+================================================================================================+ +| ``%y4`` | 4-digit year | ++-----------------------+------------------------------------------------------------------------------------------------+ +| ``%y2`` | 2-digit year | ++-----------------------+------------------------------------------------------------------------------------------------+ +| ``%m2`` | 2-digit month | ++-----------------------+------------------------------------------------------------------------------------------------+ +| ``%m1`` | 1- or 2-digit month | ++-----------------------+------------------------------------------------------------------------------------------------+ +| ``%mc`` | 3-character month abbreviation | ++-----------------------+------------------------------------------------------------------------------------------------+ +| ``%d2`` | 2-digit day of month | ++-----------------------+------------------------------------------------------------------------------------------------+ + +JULES will automatically detect the period (or frequency) of files based on the specific substitution strings in the following manner: + +.. figure:: time_templating_flow_diagram.png + :alt: Time templating flow diagram + + Flow diagram showing detection of file period from time templated string + +This means that monthly files must also have a year substitution string present, and daily files must have both month and year substitution strings present. Only yearly, monthly and daily files are allowed with time templating, with each file containing a single period (year, month or day respectively) of data. For yearly files, the first data in each file must apply from 00:00:00 on 1st January for each year. For monthly files, the first data in the file must apply from 00:00:00 on the 1st of the month. For daily files, the first data in the file must apply from 00:00:00 on the given day. Other configurations can be specified using a list of files with their respective start times. + + +Variable name templating +------------------------ + +Variable name templating can be used when related variables are stored in separate files with file names that are identical apart from a section that indicates what variable is in each file. Examples of the use of this are given in the next section. JULES will automatically detect if the variable name substitution string - ``%vv`` - is present in a file name, and apply variable name templating if appropriate. + + +Examples of file name templating +-------------------------------- + +Time templating only +~~~~~~~~~~~~~~~~~~~~ + +Data is in monthly files with all related variables in the same file. + +Template: + +.. code-block:: none + + /data/met_data_%y4%m2.nc + +Example filenames: + +.. code-block:: none + + /data/met_data_199001.nc + /data/met_data_199002.nc + ... + /data/met_data_200410.nc + +Variable name templating only +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ancillary (non-time-varying) data with each variable in similarly named but separate files. + +Template: + +.. code-block:: none + + /ancil/soil_%vv.nc + +Example filenames: + +.. code-block:: none + + /data/soil_satcon.nc + /data/soil_sathh.nc + +Time and variable name templating together +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Data is in monthly files with each variable in similarly named but separate files. + +Template: + +.. code-block:: none + + /data/%vv_%y4%mc.nc + +Example filenames: + +.. code-block:: none + + /data/Rain_1990jan.nc + /data/Wind_1990jan.nc + ... + /data/Rain_2000oct.nc + /data/Wind_2000oct.nc + +Variable name templating with a list of files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Data in 6-monthly files with each variable in similarly named but separate files. + +Since the time templating cannot handle 6-monthly files, the files and their start times must be specified as a list. However, variable name templating can still be used. + +Also note that it is possible to use a substitution string more than once in a template. + +Template list: + +.. code-block:: none + + ./%vv/met_%vv_199001.nc + ./%vv/met_%vv_199007.nc + ... + ./%vv/met_%vv_199801.nc + +Example filenames: + +.. code-block:: none + + ./Rain/met_Rain_199001.nc + ./Wind/met_Wind_199001.nc + ./Rain/met_Rain_199007.nc + ./Wind/met_Wind_199007.nc + ... + ./Rain/met_Rain_199801.nc + ./Wind/met_Wind_199801.nc diff --git a/doc/source/input/interp_examples.png b/doc/source/input/interp_examples.png new file mode 100644 index 0000000000000000000000000000000000000000..62113f1772b9b59a82fdebc7cd1ddf106b60937d GIT binary patch literal 90819 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
    oyzb<-#k3b?}yqv)zQDlti^$_eJR0*-m z`Rrnnne;D8C#+jw9!ToLvITRvi&3y6eBag8B_aF#B_9Tm)9@#5!sZVp7MI%Lbx;X! zFTtO$^5M0#-pH@{Vc>HJw_t}{-&p@d zl8N*NW~nHP*V!=vnQL1${TNv+4MZKi!g}NY3b0ru5o##VH_0gKLFN(!B~g@l_aQGF z{*skoVW9ijgBAqBjNbs>phyd3886D z77HK-W4?;7vgMDKk)ZgLEH-9C6ylQzg?G|p_(NRIx7$P_m;$K2co7+b1Qq4j!ufOv zGSDeuB=vzL9COSNR*4YCOl835lGI-UUd zuxuhtB9NroBY&WQ1e=MaB|Y;gcm&*2+K&|QKF%5l;rkKq4fOPBKkqhKwceA3eUd+x z|CBBYh9Oe>y_*>r@QAc{QCA~+gO=C5U!SVT_|-vb9j*shK6DCh6*h3me6qpTd_jTm9zy(=L29fn;C zF+(uPb$8G?Pfx;VdL0StW?OlTXIV^Cl%*Gkx=y5p0dy5pmxkcLnYtQ^@dc7co!tWF zJR0TF%-(Cb8d_vExW0Wt4!MZlTc;PD^FqdCJ=q7QueON7t^-g+$89iQ3|nqL30HBR z{)R?HP(;_1x3tWhY`JYP^I?a2ALMwB!-E{wDu-Q$HRiZOF^VsC1%%n>77B~)2|+u) zLsXNncdW?=8&Q781SnUoO9DYe@eiu92vbc!P%+-T=(jcJC08(Dh`<9j$b z(#fZLEUC&FgAi9gi^Rpk5G70*`E)SQh|!B6yLXZAL;SuEw>R%xHx!mn=xf)j;gq&;bj)-(&aCOq zgYN`xgq@xolAdkQKrDxTT#{QW+^|MMVfK^OaSW;mBW1)}=9q%7q~GJfTW|qvVN|?f zbs?N&T#GMNo_gc?z?Ne&N+!DvTd1Rzgy)u$((OHt&Uetk2_01}EiG-F39y8@oIHC3 z`cHEUm!=oYsN+HLWpE;eFB9AyS|v8CvBj;s5-pt>R%%W$X2SF!NNZ5edWS`r=n!ad zom+_;I#AIajhqN~@LK;7d)ypH3p2BnTMX!>3rklW(iIisMAp(?uqU^Z1xD>6VpqNKb z+LuJtS{x8>@rSA`ZXqE?41y{kY67inn7jXScTsPNdt}E@udGy)FgEl=p~1HRYZshn zP|=n7Yu{@7b~{B)G52vpLh*pm86|@I9S*N^lvDXG1}177>V5qK%PJ}qoyBUNwnnha zMBOWR^5n@-B^7Ht%Di4}@~+vWitJUu{+YFdBw-bj&=iQgBGMokzYkTc$uE2VKB3;@ zqluVRXF%8lWI__QrZ?E%hd~|kf!05J;L)rb{^jC9n1h*Dc0!qRa&E3Im&gTK9T@6$ zNw`adHG|6dOWsDiU%2BA!N*HF(DBT>A`-1(X<=cb#<)DV{s1J0qTJjx=vF6p_p@-`0wFI=q^sCH(@Q@p&?;;bT9bu^ zMP8Ey_LbaNf8Y;`RX%^{k*1ql{^k3%)h#VMa0@N>ctiz^`BTn!Pyg5-lw=A&Kg+S+ z(kn*!NMA8EHD8@{uq+!OZLnLBm~y~+PwK;dwdsR^wDcZ4qK&Bu zwaVAWXA(MNDRalK4{U^)k_N&);ky(h-RD{!y-cjYr;NZV&XoKDC^Du?0PPTxSN=8K{lwZ<2o)72z3&89Wh~4 z*)(e!8p40**_z?IsOacdKO|R{ms`cZ@R|+|3?v!{=wu6n<8~TDLqd0tA=yKd(w*-@ zej;HVfGW|Hu4QDG09XHnDhjfLqx262Mt9pePfsCI^}}rU0|bHfzUJ^IF>Qs_CQxK7 z+89ZMq8!vl%fS{t+V!bBDpIZtF4W$xw;RL0Z9{B8YkUQcI8uZ_r%7KMaRG_VQBxq* zRsfu~LxZ{H-XQi!SM!7+o2$_k@OK;*`4#Uf1IgJwH zgx{P>oafMPDCb2Xo2V=3y&=fM13ia+s3$P62|d7bO-)a0IUbRAAAbrQICbK%BUQ$_ z`)w9dC6s=j6alQR8znpc#qdjxnz@tO+*llnZM$kx5P0VoLr zn8?N!?nhf%6ah+7rbY|D$7wtIi|+~9zHJ*9;T;OQ;fFgs`CJGqy@FHD?ctJRRa+ibCmV=4-Q_kI2c*$LQAME zBq2Wp-pM8FHLGFyy#tvdv?$I286{wP0&7IT;o&)A-F)EJ&=W@q$tDp160olmB@G}+ zAGyIOU$VC9t)Fdn7yJJdN%9(?tdT8=JUqDI1Hc{C$PAM(%}3HzaV0I}l-T>`W7DU& zj+S;1Zk-WsYd5~fx+fybB%T8g7>8zD+tPu&E9^nIB^E)?s%f3VCU*Jey0dI?46*s>sDIF8Bg|c0Cx0*>BxB3Aq0} z0o!qNpW490AtXwf4J%5=>CH5OJQJ;i0XVXxtAs&Dz>(NXhaEPpJm=z)i)dVp^PNFN zkcR+^wfL`kK*vZOT1N|a19B3UetKJ3= z_J=U2!agPh(k8W-;fJtkW+jb`*#r9sBeMSq@S8Wn8Tk>^2jKh}PM-OA!p4A5aEd;D zEuI*R@F^r3ZX~3Hm+vKF@txMxOXmqZ746ez$1tO?n{fT3=kSnkY1BDJ40wz`6(1im zHl`X#A4M^M2yhL^A2IBKY5~Y(%j1;soK8H*fm5GH*ufAJ4LD#8GT1hALa7Pkss_); zDo;sQ{5l|mE<3`7oQ-M<2})l~a(B9ZB^YY0ENg+oS< za3)308%4*!mQn{l!4$P!;c;;ymr^f21jJi+mecnD7JnPREZ-$J0E=NnFB6j!IK)We zRzF)dA!kdLJ$nR*L4mZx_0tjp?K#YqB!rHbXlC&7*IwNX^6Y^woQj^_V*>e}DJpCN z3iir^jTxy4c-uQN$YBm*~P}}2}9u| z^=EQ1u6G!B^AOmb-HxI5mgZ&x<_ENBb4|LYmTdyl`x0Da+up`pxsrADFZlhad(Dr% z`uOeu&k?&XVnb~f24QoS=~-6`Zj?o0lxVz66VHU_ zaH9$&oP-SDzNr_IB7zS@GE;IIE)7}J!DxgJ2RPF(9ZuWQhUuDwO!IHt9mDZx?=@nO zBf!n&AuJH_x7)cjJNwt+}**a0>oL`*0?7BIR=Op(3yrs zgjXwzI&nuL1*^r*RsiuY#zXzdu?rX-=IELTX)59p@lts`!1^8$5G>K2P&gxA3)hZ9 zTh`#9;5o;lP!C&uoU8%yQ#ja}cLoqg83;VmyN*?*A_Iw8AP#ROtUk%(eKR=LAI&U= zA}|h}H7#{sr`Lb`iW63KSkLmp_F6Y8!j1vweCZibCo)VH7OOH{ocxOIDi#DxPT~1m zSUWFSDjnq;M-xW?fv<&vy2L0jV=W@gLc5>!w{g(LKDCos)6b>PXFlo8m=)rR{4Ds3 zw8LP+*0yJj=ltOuwzCGKy>|7Eb8cz%Q>%hq-zUbueHQ6h%&aITdqnJfZ_t*k7qsBV zonPR!^k&PNd)G6ACN?oDtD~g@QJYY)l<8B|{Iljt$fY0Il3k)YLx)v7P4oTYg%^vL zZg>s~KKc&|PS0lP+x|EV{!cE}|BgR2?lahM7W3|f=jp>Bqg*j>+_sJRVf-Phwp3OZ z>3uAUH=jJ&i{^iEXfxn-r=j}Yxeh&hV2ok$1_YpqIjN_&qXGj-eK4S>Aq@-;e!WT0 zQHJx~hY=BUfVZIdFq}+Hi=S!T@h?(P5krJ3Bd+&#bd-T&oGJ25#`DM?7^tJ)h|-2# zFncBNXJnzwh&QLPxdn)RA7c%Nh_40-qYmc%N?g3WbQ9#6tq{C>-xC$cPa@HjDl442 zc;L^#VUa3=(p5du@}dE`FyVku=5mr)(8b^hO;`_L@8E%ul?CM%tZn@d&vMX^2wjI^ z*jE#KLF7`5gq$Dl_1I_IzX)up$DyG7_5Ga$EEBt=t{;HUCE@8#D41Y9Rq*kVA@$+Z zi_qO`0^AP=c6KyTC4zQ6X*+Yz;NJ|_9-KD$WAc#vq1Qor4p^T=f>$*rHwg;EFCRX5 z09U%t@(O*xXmIl*{tEx1COL%WbkJJ;e__lso56w z1hgT%VwG?LNvtc-ZSF%#X^Js0ew9oQT3+tHTWWW3XlP@cW=xUBmY9YF5EHHy7u)S2 zdI1!HL;~XX7KZ>}eIb+)7TkcjO#y@AJX0aln6k@+C%%~dXGaHD wjHsjkN&Op+>?a70`1^0@asM!{hI<#*=)^j+T&5$UN%&J%R8z<}Z4&T50L;bRLjV8( literal 0 HcmV?d00001 diff --git a/doc/source/input/netcdf.rst b/doc/source/input/netcdf.rst new file mode 100644 index 00000000..7e4d5241 --- /dev/null +++ b/doc/source/input/netcdf.rst @@ -0,0 +1,9 @@ +NetCDF files +============ + +For gridded data, NetCDF is the only supported format. Although ASCII files can be used for data at a single location, NetCDF is also the preferred format for such data (due to the reasons discussed in :doc:`overview`). Files are not expected to use specific dimension or variable names - these are specified via the :doc:`JULES namelists `. The only expectations placed on NetCDF input are: + +* All input files use the same grid. +* All input files use the same dimension names (for grid dimensions, any additional dimensions and the time dimension). +* The dimensions for each variable appear in the correct order - ``(points, z1, z2, ..., t)`` for a 1D grid and ``(x, y, z1, z2, ..., t)`` for a 2D grid, where the ``z1, z2, ...`` (levels) and ``t`` (time) dimensions are only present when the variable and context in which the variable is being used require them. +* If using NetCDF for data at a single location, the grid dimensions are still expected to exist with size 1. \ No newline at end of file diff --git a/doc/source/input/overview.rst b/doc/source/input/overview.rst new file mode 100644 index 00000000..4a03f5a0 --- /dev/null +++ b/doc/source/input/overview.rst @@ -0,0 +1,13 @@ +Input files for JULES +===================== + + +The recommended file format for use with JULES is NetCDF, although an ASCII format is also supported for data at a single location only. NetCDF is recommended since in this format, the metadata are provided in a standardised manner that many other tools and applications can interpret. The file handling code of JULES is written in a modular way that aims to make it easy for the user to add support for other file formats if they desire. Any user that does this is strongly encouraged to contribute their code back to the community. + + +.. toctree:: + principles + ascii + netcdf + file-name-templating + temporal-interpolation diff --git a/doc/source/input/principles.rst b/doc/source/input/principles.rst new file mode 100644 index 00000000..121869de --- /dev/null +++ b/doc/source/input/principles.rst @@ -0,0 +1,23 @@ +General principles +================== + +JULES supports the input and output of gridded data on both 1D (e.g. vector of land points) and 2D (e.g. latitude/longitude) grids, with zero or more additional 'levels' dimensions (e.g. for soil layers). A 2D grid is the usual way to think about gridded data, i.e. with x and y dimensions; however a 1D grid can be more flexible and space-efficient. An example of a 1D grid is a land-points-only grid (as used in the GSWP2 and WATCH datasets). In this case, these data are supplied as a vector of land points, which avoids storing information about sea and sea-ice points that are not being processed. + +In JULES, the input grid is comprised of the following information: + +#. Whether the grid is 1D or 2D (ASCII or NetCDF). +#. The size of each grid dimension (ASCII or NetCDF). +#. The name of each dimension in the file(s) (NetCDF only). + +The input grid is specified by the user in the namelist :nml:lst:`JULES_INPUT_GRID`. The model grid is then constructed by selecting the desired points from this input grid, the default being that only the land points in the input grid will be processed. All output is on the model grid. + +.. note:: + All input data must use the same grid, including any ancillaries and initial conditions. + +JULES infers the format of input files from the file extension. The recognised file extensions are: + +ASCII files + ``.asc``, ``.txt`` and ``.dat`` + +NetCDF files + ``.nc`` and ``.cdf`` \ No newline at end of file diff --git a/doc/source/input/temporal-interpolation.rst b/doc/source/input/temporal-interpolation.rst new file mode 100644 index 00000000..f838c809 --- /dev/null +++ b/doc/source/input/temporal-interpolation.rst @@ -0,0 +1,63 @@ +Temporal interpolation +====================== + +Time-varying data as inputs into JULES are provided in two types - instantaneous states (e.g. air temperature, surface pressure, lai) or fluxes (e.g. radiation, precipitation). Because the data are on discrete timesteps, the value of an instantaneous variable applies at the timestamp (e.g. air temperature at 0800). However, values of the fluxes represent averages over the data timestep (e.g. 3-hour average rates). Different datasets supply the data as averages over the previous data timestep (backwards average) or the next data timestep (forwards average). + +In order for the numerics to remain stable, it is recommended to run JULES with a model timestep of 1 hour or shorter. If the data timestep is longer than the model timestep, interpolation is required. How interpolation is performed for a particular variable depends on whether the variable is an instantaneous state or a flux. + + +Interpolation flags +------------------- + +When JULES needs to know what type of interpolation to use for a variable, the following flags are used. + + +``i`` + Linear interpolation from the data timestep to the model timestep. + + For instantaneous data (e.g. air temperature, surface pressure), this is almost always the flag that should be used. + +``nb``, ``nc`` and ``nf`` + Values will be held constant with time for all model timesteps associated with a particular data timestep. + + One of these flags should be used for flux variables that are *discontinuous* by nature, e.g. precipitation. + + ``nb`` should be used if the dataset uses backwards average values, ``nf`` should be used if the data set uses forwards average values and ``nc`` should be used if the dataset uses centred average values (this is quite rare). + +``b``, ``c`` and ``f`` + Data is interpolated using a simplified version of the Sheng and Zwiers (1998) [#]_ method that conserves the period means of the data. + + One of these flags should be used for flux variables that are *continuous* in nature, e.g. radiation. + + In order to ensure conservation of the average, these flags should be used only if the data period is an even multiple of the model timestep (i.e., if ``data_period = 2 * n * timestep_len; n = 1, 2, 3, ...``). The curve-fitting process tends to produce occasional values near turning points that fall outside the range of the input values. + + Similar to above, ``b`` should be used if the dataset uses backwards average values, ``f`` should be used if the data set uses forwards average values and ``c`` should be used if the dataset uses centred average values. + + +In order to perform interpolation, JULES may require input data for one or two data timesteps that fall before or after the times for the integration: + ++-----------------------+------------------------------------------------------------------------------------------------------+ +| Flag | Extra data timesteps required | ++=======================+======================================================================================================+ +| ``nf`` | Only requires data that falls within the integration times | ++-----------------------+------------------------------------------------------------------------------------------------------+ +| ``i``, ``nb``, ``nc`` | Requires one data timestep beyond the end of the integration | ++-----------------------+------------------------------------------------------------------------------------------------------+ +| ``nb`` | Requires two data timesteps beyond the end of the integration | ++-----------------------+------------------------------------------------------------------------------------------------------+ +| ``nf`` | Requires one data timestep before the start and one data timestep beyond the end of the integration | ++-----------------------+------------------------------------------------------------------------------------------------------+ +| ``nc`` | Requires one data timestep before the start and two data timesteps beyond the end of the integration | ++-----------------------+------------------------------------------------------------------------------------------------------+ + +Also, note that for centred data (flags ``c`` and ``nc``) the time of the data should be given as that at the start of the averaging period, rather than the centre, e.g. the 3-hour average over 06H to 09H, centred at 07:30H, should be treated as having timestamp 06H. + +.. figure:: interp_examples.png + :alt: Examples of JULES interpolation modes + + Examples of data interpolated with ``i``, ``nb``, ``nf``, ``b`` and ``f``, plotted against the data they are derived from + + +.. rubric:: Footnotes + +.. [#] Sheng and Zwiers (1998) An improved scheme for time-dependent boundary conditions in atmospheric general circulation models, Climate Dynamics, 14, 609-613. diff --git a/doc/source/input/time_templating_flow_diagram.png b/doc/source/input/time_templating_flow_diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..bff8f7dd129ef9baa31129058df025ca2b9d86d1 GIT binary patch literal 61631 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 XIg5*${oGAI00000NkvXXu0mjf(D+7` literal 0 HcmV?d00001 diff --git a/doc/source/jules_logo_pdf.png b/doc/source/jules_logo_pdf.png new file mode 100644 index 0000000000000000000000000000000000000000..06a0bca404e9c076f2b5814a176c38c74d162ed1 GIT binary patch literal 204682 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Ä=$_L1_>*-M=X4U&`jOG$)=8~$iMwco?>8wJ*bLI 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�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 Ki0B?vT)}^qH=&OJ literal 0 HcmV?d00001 diff --git a/doc/source/namelists/ancillaries.nml.rst b/doc/source/namelists/ancillaries.nml.rst new file mode 100644 index 00000000..99502246 --- /dev/null +++ b/doc/source/namelists/ancillaries.nml.rst @@ -0,0 +1,2004 @@ +``ancillaries.nml`` +=================== + + +This file sets up spatially varying ancillary values. It contains the following namelists: :nml:lst:`JULES_FRAC`, :nml:lst:`JULES_VEGETATION_PROPS`, :nml:lst:`JULES_SOIL_PROPS`, :nml:lst:`JULES_TOP`, :nml:lst:`JULES_PDM`, :nml:lst:`JULES_AGRIC`, :nml:lst:`JULES_CROP_PROPS`, :nml:lst:`JULES_IRRIG_PROPS`, :nml:lst:`JULES_RIVERS_PROPS`, :nml:lst:`JULES_WATER_RESOURCES_PROPS`, :nml:lst:`URBAN_PROPERTIES` , :nml:lst:`JULES_CO2` and :nml:lst:`JULES_FLAKE`. + +Data associated with each of these namelists can optionally be read from the dump file (if present) by setting ``read_from_dump`` to true. This functionality provides closer alignment with UM functionality and can help ensure that the correct ancillary data remain associated with the model state. + +``JULES_FRAC`` namelist members +------------------------------- + +.. nml:namelist:: JULES_FRAC + +This namelist specifies the fraction of the land area in each gridbox that is covered by each of the surface types. If :nml:mem:`JULES_VEGETATION::l_veg_compete` = TRUE, then the fraction of each surface type is modelled and the initial state should be specified in :nml:lst:`JULES_INITIAL`. In all other cases, it must be read here. + +Note that all land points must be either soil points (indicated by values > 0 of the saturated soil moisture content), or land ice points (indicated by the fractional coverage of the ice surface type - if used - being one). The fractional cover of the ice surface type in each gridbox must be either zero or one - there cannot be partial coverage of ice within a gridbox. + +If using either URBAN-2T or MORUSES then the total *urban* fraction can be specified instead of the separate :nml:mem:`JULES_SURFACE_TYPES::urban_canyon` and :nml:mem:`JULES_SURFACE_TYPES::urban_roof` contributions. When initialising, if the roof fraction is zero, the canyon fraction will be interpreted as the total *urban* fraction and be partitioned according to canyon fraction (W/R, see :nml:lst:`URBAN_PROPERTIES`). + +.. note:: For runs with dynamic vegetation (TRIFFID, :nml:mem:`JULES_VEGETATION::l_triffid` = TRUE) and :nml:mem:`JULES_VEGETATION::l_veg_compete` = TRUE, then the fraction of each surface type is being modelled and the initial state should be specified in :nml:lst:`JULES_INITIAL` (which will override any settings given in this section). In all other cases, frac must be read here. + +.. nml:member:: read_from_dump + + :type: logical + :default: F + + TRUE + Populate variables associated with this namelist from the dump file. All other namelist members are ignored. + + FALSE + Use the other namelist members to determine how to populate variables. + + +.. nml:member:: file + + :type: character + :default: None + + The name of the file to read surface type fractional coverage data from. + + +.. nml:member:: frac_name + + :type: character + :default: 'frac' + + The name of the variable containing the surface type fractional coverage data. + + .. note:: + This is only used for NetCDF files. + For ASCII files, the surface type fractional coverage data is expected to be the first (ideally only) variable in the file. + + + + .. note:: + The open water fraction of this array (given by :nml:mem:`JULES_SURFACE_TYPES::lake`) should contain permanent water, and wetland extents that are not being otherwise simulated. + If groundwater inundation is being simulated (i.e. TOPMODEL is active :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE and therefore fsat is being calculated) then all groundwater-maintained wetlands must be excluded from :nml:mem:`JULES_FRAC::frac_name`. + If overbank inundation is being simulated (i.e. :nml:mem:`JULES_RIVERS::l_riv_overbank` = TRUE) then all fluvial wetlands must be excluded from :nml:mem:`JULES_FRAC::frac_name`. + Finally, note that simulation of a potential future climate scenario with greatly reduced areas for lakes that are currently 'permanent' would require suitable modification of the ancillary provided here. + + In the file, the variable must have a single levels dimension of size ``ntype`` called :nml:mem:`JULES_INPUT_GRID::type_dim_name`, and should not have a time dimension. + + + +``JULES_VEGETATION_PROPS`` namelist members +------------------------------------------- + +.. nml:namelist:: JULES_VEGETATION_PROPS + + +This namelist specifies how spatially-varying properties of vegetation should be set. + +At present only one variable - ``t_home_gb`` - can be specified via this namelist, and this is only required if thermal adaptation of photosynthetic capacity is selected (:nml:mem:`JULES_VEGETATION::photo_acclim_model` = 1 or 3). + +Note that Leaf Area Index and vegetation height are specified elsewhere - see :nml:lst:`JULES_PRESCRIBED`. + + +.. nml:member:: read_from_dump + + :type: logical + :default: F + + TRUE + Populate variables associated with this namelist from the dump file. All other namelist members are ignored. + + FALSE + Use the other namelist members to determine how to populate variables. + + +.. nml:member:: read_list + + :type: logical + :default: F + + Switch controlling how ancillary file names are determined. + + TRUE + Use list of file names; one per line for each of :nml:mem:`nvars`. Files in list cannot use :doc:`variable name templating `. + + FALSE + Use a single file for variables or use variable name template. + + For an example where :nml:mem:`read_list` = TRUE, please see the ``OASIS_RIVERS`` :ref:`Example of coupling request`. + + +.. nml:member:: file + + :type: character + :default: None + + The file (or list of files) from which to read the vegetation properties. + + If :nml:mem:`read_list` is TRUE, this is the file from which to read the list of file names; one per line for each of :nml:mem:`nvars` variables. The file names cannot use :doc:`variable name templating `. If :nml:mem:`use_file` is FALSE for a particular variable, the line may contain ''. + + If :nml:mem:`read_list` is FALSE, this is the file or :doc:`file name template `. + + If :nml:mem:`use_file` is FALSE for every variable, this will not be used. + + +.. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of vegetation property variables that will be provided (see :ref:`list-of-vegetation-params`). + + +.. nml:member:: var + + :type: character(nvars) + :default: None + + List of vegetation variable names as recognised by JULES (see :ref:`list-of-vegetation-params`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + + +.. nml:member:: use_file + + :type: logical(nvars) + :default: T + + For each JULES variable specified in :nml:mem:`var`, this indicates if it should be read from the specified file or whether a constant value is to be used. + + TRUE + The variable will be read from the file. + + FALSE + The variable will be set to a constant value everywhere using :nml:mem:`const_val` below. + + +.. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = TRUE, this is the name of the variable in the file containing the data. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + This is not used for variables where :nml:mem:`use_file` = FALSE, but a placeholder must still be given in that case. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + + +.. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name in place of the variable name substitution string. + + If the file name does not use variable name templating, this is not used. + + +.. nml:member:: const_val + + :type: real(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = FALSE, this is a constant value that the variable will be set to at every point. + + This is not used for variables where :nml:mem:`use_file` = TRUE, but a placeholder must still be given in that case. + + +.. _list-of-vegetation-params: + +List of vegetation parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabularcolumns:: |p{2cm}|p{9cm}| + ++-----------------+--------------------------------------------------------------------------------------+ +| Name | Description | ++=================+======================================================================================+ +| ``t_home_gb`` | Average temperature (home temperature) for thermal adaptation of photosynthetic | +| | capacity (K), e.g. a multi-decadal average or pre-industrial temperature. | +| | Suggestions as to how to calculate a suitable temperature can be found in | +| | :ref:`Kattge and Knorr (2007)` or | +| | :ref:`Kumarathunge et al (2019)`. This variable should not | +| | have a time dimension nor any "levels" dimension. | ++-----------------+--------------------------------------------------------------------------------------+ + + + + +``JULES_SOIL_PROPS`` namelist members +------------------------------------- + +.. nml:namelist:: JULES_SOIL_PROPS + +This namelist specifies how spatially varying soil properties should be set. + +.. nml:member:: read_from_dump + + :type: logical + :default: F + + TRUE + Populate variables associated with this namelist from the dump file. All other namelist members are ignored. + + FALSE + Use the other namelist members to determine how to populate variables. + + +.. nml:member:: const_z + + :type: logical + :default: F + + Switch indicating if soil properties are to be uniform with depth. + + TRUE + Soil characteristics do not vary with depth. + + FALSE + Soil characteristics vary with depth. For any variable this is ignored if a constant value is to be used (see :nml:mem:`const_val`). + + +.. nml:member:: read_list + + :type: logical + :default: F + + Switch controlling how ancillary file names are determined. + + TRUE + Use list of file names; one per line for each of :nml:mem:`nvars`. Files in list cannot use :doc:`variable name templating `. + + FALSE + Use a single file for variables or use variable name template. + + For an example where :nml:mem:`read_list` = TRUE, please see the ``OASIS_RIVERS`` :ref:`Example of coupling request`. + + +.. nml:member:: file + + :type: character + :default: None + + The file (or list of files) from which to read the soil properties. + + If :nml:mem:`read_list` is TRUE, this is the file from which to read the list of file names; one per line for each of :nml:mem:`nvars` variables. The file names cannot use :doc:`variable name templating `. If :nml:mem:`use_file` is FALSE for a particular variable, the line may contain ''. + + If :nml:mem:`read_list` is FALSE, this is the file or :doc:`file name template `. + + If :nml:mem:`use_file` is FALSE for every variable, this will not be used. + + +.. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of soil property variables that will be provided (see :ref:`list-of-soil-params`). + + +.. nml:member:: var + + :type: character(nvars) + :default: None + + List of soil variable names as recognised by JULES (see :ref:`list-of-soil-params`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + + +.. nml:member:: use_file + + :type: logical(nvars) + :default: T + + For each JULES variable specified in :nml:mem:`var`, this indicates if it should be read from the specified file or whether a constant value is to be used. + + TRUE + The variable will be read from the file. + + FALSE + The variable will be set to a constant value everywhere using :nml:mem:`const_val` below. + + +.. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = TRUE, this is the name of the variable in the file containing the data. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + This is not used for variables where :nml:mem:`use_file` = FALSE, but a placeholder must still be given in that case. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + + +.. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name in place of the variable name substitution string. + + If the file name does not use variable name templating, this is not used. + + +.. nml:member:: const_val + + :type: real(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = FALSE, this is a constant value that the variable will be set to at every point in every layer (overriding :nml:mem:`const_z` = FALSE). + + This is not used for variables where :nml:mem:`use_file` = TRUE, but a placeholder must still be given in that case. + + +.. _list-of-soil-params: + +List of soil parameters +~~~~~~~~~~~~~~~~~~~~~~~ + +If :nml:mem:`const_z` = FALSE, variables read from file must have a single levels dimension. For most variables this dimension must be of size :nml:mem:`JULES_SOIL::sm_levels` and called :nml:mem:`JULES_INPUT_GRID::soil_dim_name`; exceptions to this rule are indicated in the table below. + +If :nml:mem:`const_z` = TRUE, variables read from file must have no levels dimensions. + +If soil tiling is selected (:nml:mem:`JULES_SOIL::l_tile_soil` = TRUE), ancillary fields can be specified for each soil tile (:nml:mem:`JULES_SOIL::l_broadcast_ancils` = FALSE), or values can be read for one soil tile and copied to all tiles (:nml:mem:`JULES_SOIL::l_broadcast_ancils` = TRUE). + +In all cases, the variables must have no time dimension. + +.. tabularcolumns:: |p{2cm}|p{9cm}|p{3.5cm}| + ++-----------------+--------------------------------------------------------------------------------------+--------------------------------------------------+ +| Name | Description | Levels name | ++=================+======================================================================================+==================================================+ +| ``albsoil`` | Soil albedo. A single (averaged) waveband is used. | None | ++-----------------+--------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``b`` | Exponent in soil hydraulic characteristics. | :nml:mem:`JULES_INPUT_GRID::soil_dim_name` | +| | n.b. Related to the Brooks & Corey parameter lambda by b=1/lambda | | +| | and to the van Genuchten-Mualem parameter n by b=1/(n-1) | | ++-----------------+--------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``hcap`` | Dry heat capacity (J m\ :sup:`-3` K\ :sup:`-1`). | :nml:mem:`JULES_INPUT_GRID::soil_dim_name` | ++-----------------+--------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``hcon`` | Dry thermal conductivity (W m\ :sup:`-1` K\ :sup:`-1`). | :nml:mem:`JULES_INPUT_GRID::soil_dim_name` | ++-----------------+--------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``satcon`` | Hydraulic conductivity at saturation (kg m\ :sup:`-2` s\ :sup:`-1`). | :nml:mem:`JULES_INPUT_GRID::soil_dim_name` | ++-----------------+--------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``sathh`` | If :nml:mem:`JULES_SOIL::l_vg_soil` = TRUE (i.e. using van Genuchten model), | :nml:mem:`JULES_INPUT_GRID::soil_dim_name` | +| | ``sathh`` = 1 / ``alpha``, where ``alpha`` (m\ :sup:`-1`) is a parameter of the van | | +| | Genuchten model. | | +| | | | +| | If :nml:mem:`JULES_SOIL::l_vg_soil` = FALSE (using Brooks and Corey model), ``sathh``| | +| | is the soil matric suction at saturation (in pressure head units, m), i.e. the | | +| | absolute value of the soil matric potential at saturation. | | ++-----------------+--------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``sm_crit`` | Volumetric soil moisture content at the critical point (m\ :sup:`3` water per | :nml:mem:`JULES_INPUT_GRID::soil_dim_name` | +| | m\ :sup:`3` soil). If :nml:mem:`JULES_VEGETATION::l_use_pft_psi` = F, | | +| | the point at which soil moisture stress starts to restrict | | +| | transpiration is a function of ``sm_crit``, ``sm_sat`` and the pft-dependent | | +| | parameter :nml:mem:`JULES_PFTPARM::fsmc_p0_io` . | | +| | | | +| | ``sm_crit`` is also used to calculate the surface conductance of bare soil. | | ++-----------------+--------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``sm_sat`` | Volumetric soil moisture content at saturation (m\ :sup:`3` water per m\ :sup:`3` | :nml:mem:`JULES_INPUT_GRID::soil_dim_name` | +| | soil). | | +| | | | +| | .. note:: | | +| | This field is used to distinguish between soil points and land ice points. | | +| | | | +| | ``sm_sat > 0`` indicates a soil point. | | ++-----------------+--------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``sm_wilt`` | Volumetric soil moisture content at the wilting point (m\ :sup:`3` water | :nml:mem:`JULES_INPUT_GRID::soil_dim_name` | +| | per m\ :sup:`3` soil). If :nml:mem:`JULES_VEGETATION::l_use_pft_psi` = F, | | +| | ``sm_wilt`` is the limit where soil moisture stress | | +| | completely prevents transpiration. | | +| | | | +| | ``sm_wilt`` is also used to calculate soil respiration. | | ++-----------------+--------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``clay`` | Soil clay content (g clay per g soil). Only required for the 4-pool and ECOSSE soil | :nml:mem:`JULES_INPUT_GRID::sclayer_dim_name` | +| | carbon models (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3). | | +| | | | +| | .. note:: | | +| | To allow backwards compatibility when using the 4-pool model | | +| | (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2), if the clay content is | | +| | not available it is set to 0.0 in the code. | | +| | | | +| | However, this is wrong - if it is not available it should be set to 0.23. | | ++-----------------+--------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``soil_ph`` | Soil pH. Only required for the ECOSSE soil carbon model | :nml:mem:`JULES_INPUT_GRID::sclayer_dim_name` | +| | (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 3). | | ++-----------------+--------------------------------------------------------------------------------------+--------------------------------------------------+ + + +``JULES_TOP`` namelist members +------------------------------ + +.. nml:namelist :: JULES_TOP + +This namelist reads spatially varying parameter values for the TOPMODEL-type parameterisation of runoff. The values are only used if :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE. The description below is very brief. For further details, see the references under :nml:mem:`JULES_HYDROLOGY::l_top`. + + +.. nml:member:: read_from_dump + + :type: logical + :default: F + + TRUE + Populate variables associated with this namelist from the dump file. All other namelist members are ignored. + + FALSE + Use the other namelist members to determine how to populate variables. + + +.. nml:member:: read_list + + :type: logical + :default: F + + Switch controlling how ancillary file names are determined. + + TRUE + Use list of file names; one per line for each of :nml:mem:`nvars`. Files in list cannot use :doc:`variable name templating `. + + FALSE + Use a single file for variables or use variable name template. + + For an example where :nml:mem:`read_list` = TRUE, please see the ``OASIS_RIVERS`` :ref:`Example of coupling request`. + + +.. nml:member:: file + + :type: character + :default: None + + The file (or list of files) from which to read the TOPMODEL properties. + + If :nml:mem:`read_list` is TRUE, this is the file from which to read the list of file names; one per line for each of :nml:mem:`nvars` variables. The file names cannot use :doc:`variable name templating `. If :nml:mem:`use_file` is FALSE for a particular variable, the line may contain ''. + + If :nml:mem:`read_list` is FALSE, this is the file or :doc:`file name template `. + + If :nml:mem:`use_file` is FALSE for every variable, this will not be used. + + +.. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of TOPMODEL property variables that will be provided. At present, all variables are required for runs using TOPMODEL (see :ref:`list-of-topmodel-params`). + + +.. nml:member:: var + + :type: character(nvars) + :default: None + + List of TOPMODEL variable names as recognised by JULES (see :ref:`list-of-topmodel-params`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + + +.. nml:member:: use_file + + :type: logical(nvars) + :default: T + + For each JULES variable specified in :nml:mem:`var`, this indicates if it should be read from the specified file or whether a constant value is to be used. + + TRUE + The variable will be read from the file. + + FALSE + The variable will be set to a constant value everywhere using :nml:mem:`const_val` below. + + +.. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = TRUE, this is the name of the variable in the file containing the data. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + This is not used for variables where :nml:mem:`use_file` = FALSE, but a placeholder must still be given in that case. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + + +.. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name in place of the variable name substitution string. + + If the file name does not use variable name templating, this is not used. + + +.. nml:member:: const_val + + :type: real(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = FALSE, this is a constant value that the variable will be set to at every point in every layer. + + This is not used for variables where :nml:mem:`use_file` = TRUE, but a placeholder must still be given in that case. + + +.. _list-of-topmodel-params: + +List of TOPMODEL parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All of the TOPMODEL variables listed below are expected to have no levels dimensions and no time dimension. + +.. tabularcolumns:: |p{2.5cm}|L| + ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Description | ++============================+===========================================================================================================+ +| ``fexp`` | Decay factor describing how the saturated hydraulic conductivity decreases with depth below the standard | +| | soil column (m\ :sup:`-1`). | +| | | +| | Routinely set between 2 and 3 m\ :sup:`-1`. Gedney & Cox (2003, J Hydromet) used value 0.5 m\ :sup:`-1`; | +| | Niu & Yang (2003, Global & Planet. Change) suggested a global mean value of 2.0 m\ :sup:`-1`. | +| | | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``ti_mean`` | (Spatial, not temporal) mean value of the topographic index in each gridbox. | +| | Value 5.99 is the global mean given in Marthews et al. (2015, HESS) | +| | | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``ti_sig`` | (Spatial, not temporal) standard deviation of the topographic index in each gridbox. | +| | Values <0.5 are updated to =0.5 internally to allow at least some variability | +| | | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ + + +``JULES_PDM`` namelist members +------------------------------ + +.. nml:namelist :: JULES_PDM + +This namelist reads spatially varying parameter values for the PDM-type parameterisation of runoff. The values are only used if :nml:mem:`JULES_HYDROLOGY::l_pdm` = TRUE. The description below is very brief. For further details, see the references under :nml:mem:`JULES_HYDROLOGY::l_pdm`. + + +.. nml:member:: read_list + + :type: logical + :default: F + + Switch controlling how ancillary file names are determined. + + TRUE + Use list of file names; one per line for each of :nml:mem:`nvars`. Files in list cannot use :doc:`variable name templating `. + + FALSE + Use a single file for variables or use variable name template. + + For an example where :nml:mem:`read_list` = TRUE, please see the ``OASIS_RIVERS`` :ref:`Example of coupling request`. + + +.. nml:member:: file + + :type: character + :default: None + + The file (or list of files) from which to read the PDM properties. + + If :nml:mem:`read_list` is TRUE, this is the file from which to read the list of file names; one per line for each of :nml:mem:`nvars` variables. The file names cannot use :doc:`variable name templating `. If :nml:mem:`use_file` is FALSE for a particular variable, the line may contain ''. + + If :nml:mem:`read_list` is FALSE, this is the file or :doc:`file name template `. + + If :nml:mem:`use_file` is FALSE for every variable, this will not be used. + + +.. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of PDM property variables that will be provided (see :ref:`list-of-pdm-params`). At present, only the topographic slope can be provided. + + +.. nml:member:: var + + :type: character(nvars) + :default: None + + List of PDM variable names as recognised by JULES (see :ref:`list-of-pdm-params`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + + +.. nml:member:: use_file + + :type: logical(nvars) + :default: T + + For each JULES variable specified in :nml:mem:`var`, this indicates if it should be read from the specified file or whether a constant value is to be used. + + TRUE + The variable will be read from the file. + + FALSE + The variable will be set to a constant value everywhere using :nml:mem:`const_val` below. + + +.. nml:member:: var_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = TRUE, this is the name of the variable in the file containing the data. + + This is not used for variables where :nml:mem:`use_file` = FALSE, but a placeholder must still be given. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + + +.. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name in place of the variable name substitution string. + + If the file name does not use variable name templating, this is not used. + + +.. nml:member:: const_val + + :type: real(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = FALSE, this is a constant value that the variable will be set to at every point in every layer. + make html + This is not used for variables where :nml:mem:`use_file` = TRUE, but a placeholder must still be given. + + +.. _list-of-pdm-params: + +List of PDM parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All of the PDM variables listed below are expected to have no levels dimensions and no time dimension. + +.. tabularcolumns:: |p{2.5cm}|L| + ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Description | ++============================+===========================================================================================================+ +| ``slope`` | Mean value of the topographic slope in the gridbox (deg). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ + + +``JULES_AGRIC`` namelist members +-------------------------------- + +.. nml:namelist:: JULES_AGRIC + +If the TRIFFID vegetation model is used, the fractional area of agricultural land in each gridbox is specified using this namelist. Otherwise, the values in this namelist are not used. + + +.. nml:member:: read_from_dump + + :type: logical + :default: F + + TRUE + Populate frac_agr, frac_past, and frac_biocrop from the dump file. All other namelist members are ignored. + + FALSE + Use the other namelist members to determine how to populate variables. + + +.. nml:member:: zero_agric + + :type: logical + :default: T + + Switch used to simplify the initialisation of agricultural fraction. + + TRUE + Set agricultural fraction at all points to zero. + + FALSE + Set agricultural fraction using specified data. + + +.. nml:group:: Used if :nml:mem:`zero_agric` = FALSE and the input grid consists of a single location + + .. nml:member:: frac_agr + + :type: real + :default: None + + The agricultural fraction for the single location. + + +.. nml:group:: Used if :nml:mem:`zero_agric` = FALSE and the input grid consists of more than one location + + .. nml:member:: file + + :type: character + :default: None + + The name of the file to read agricultural fraction data from. + + + .. nml:member:: agric_name + + :type: character + :default: 'frac_agr' + + The name of the variable containing the agricultural fraction data. + + In the file, the variable must have no levels dimensions and no time dimension. + + +.. nml:member:: zero_past + + :type: logical + :default: T + + Switch used to simplify the initialisation of pasture fraction. Pasture fraction can only be used if :nml:mem:`JULES_VEGETATION::l_trif_crop` is TRUE. + + TRUE + Set pasture fraction at all points to zero. + + FALSE + Set pasture fraction using specified data. + + +.. nml:group:: Used if :nml:mem:`zero_past` = FALSE and the input grid consists of a single location + + .. nml:member:: frac_past + + :type: real + :default: None + + The pasture fraction for the single location. + + +.. nml:group:: Used if :nml:mem:`zero_past` = FALSE and the input grid consists of more than one location + + .. nml:member:: file_past + + :type: character + :default: None + + The name of the file to read pasture fraction data from. + + + .. nml:member:: pasture_name + + :type: character + :default: 'frac_past' + + The name of the variable containing the pasture fraction data. + + In the file, the variable must have no levels dimensions and no time dimension. + + +.. nml:member:: zero_biocrop + + :type: logical + :default: T + + Switch used to simplify the initialisation of bioenergy fraction. Bioenergy fraction can only be used if :nml:mem:`JULES_VEGETATION::l_trif_biocrop` is TRUE. + + TRUE + Set bioenergy fraction at all points to zero. + + FALSE + Set bioenergy fraction using specified data. + + +.. nml:group:: Used if :nml:mem:`zero_biocrop` = FALSE and the input grid consists of a single location + + .. nml:member:: frac_biocrop + + :type: real + :default: None + + The bioenergy fraction for the single location. + + +.. nml:group:: Used if :nml:mem:`zero_biocrop` = FALSE and the input grid consists of more than one location + + .. nml:member:: file_biocrop + + :type: character + :default: None + + The name of the file to read bioenergy fraction data from. + + + .. nml:member:: biocrop_name + + :type: character + :default: 'frac_biocrop' + + The name of the variable containing the bioenergy fraction data. + + In the file, the variable must have no levels dimensions and no time dimension. + + +.. nml:group:: Specify the day of year on which harvesting occurs. Only used if :nml:mem:`JULES_VEGETATION::l_trif_biocrop` = TRUE. A placeholder value must be set for all PFTs, though will only be used for PFTs with :nml:mem:`JULES_TRIFFID::harvest_type_io` = 2. + + + .. nml:member:: read_harvest_doy_from_dump + + :type: logical + :default: F + + TRUE + Populate harvest_doy from the dump file. All other namelist members are ignored. + + FALSE + Use the other namelist members to determine how to populate variables. + + + .. nml:member:: file_harvest_doy + + :type: character + :default: None + + The name of the file to read harvest day-of-year data from. + + + .. nml:member:: harvest_doy_name + + :type: character + :default: 'harvest_doy' + + The name of the variable containing the harvest day-of-year data. + + .. note:: + This is only used for NetCDF files. + For ASCII files, the harvest day-of-year data is expected to be the first (ideally only) variable in the file. + + +``JULES_CROP_PROPS`` namelist members +------------------------------------- + +.. nml:namelist:: JULES_CROP_PROPS + + +.. nml:member:: read_from_dump + + :type: logical + :default: F + + TRUE + Populate variables associated with this namelist from the dump file. All other namelist members are ignored. + + FALSE + Use the other namelist members to determine how to populate variables. + + +.. nml:member:: read_list + + :type: logical + :default: F + + Switch controlling how ancillary file names are determined. + + TRUE + Use list of file names; one per line for each of :nml:mem:`nvars`. Files in list cannot use :doc:`variable name templating `. + + FALSE + Use a single file for variables or use variable name template. + + For an example where :nml:mem:`read_list` = TRUE, please see the ``OASIS_RIVERS`` :ref:`Example of coupling request`. + + +.. nml:member:: file + + :type: character + :default: None + + The file (or list of files) from which to read the crop properties. + + If :nml:mem:`read_list` is TRUE, this is the file from which to read the list of file names; one per line for each of :nml:mem:`nvars` variables. The file names cannot use :doc:`variable name templating `. If :nml:mem:`use_file` is FALSE for a particular variable, the line may contain ''. + + If :nml:mem:`read_list` is FALSE, this is the file or :doc:`file name template `. + + If :nml:mem:`use_file` is FALSE for every variable, this will not be used. + + +.. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of crop property variables that will be provided (see :ref:`list-of-spatially-varying-crop-properties`). + + +.. nml:member:: var + + :type: character(nvars) + :default: None + + List of variable names for spatially-varying crop properties as recognised by JULES (see :ref:`list-of-spatially-varying-crop-properties`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + + +.. nml:member:: use_file + + :type: logical(nvars) + :default: T + + For each JULES variable specified in :nml:mem:`var`, this indicates if it should be read from the specified file or whether a constant value is to be used. + + TRUE + The variable will be read from the file. + + FALSE + The variable will be set to a constant value everywhere using :nml:mem:`const_val` below. + + +.. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = TRUE, this is the name of the variable in the file containing the data. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + This is not used for variables where :nml:mem:`use_file` = FALSE, but a placeholder must still be given in that case. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + + +.. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name in place of the variable name substitution string. + + If the file name does not use variable name templating, this is not used. + + +.. nml:member:: const_val + + :type: real(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = FALSE, this is a constant value that the variable will be set to at every point in every layer. + + This is not used for variables where :nml:mem:`use_file` = TRUE, but a placeholder must still be given in that case. + + +.. _list-of-spatially-varying-crop-properties: + +List of spatially-varying crop properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All of the crop variables listed below are expected to have a single levels dimension of size :nml:mem:`JULES_SURFACE_TYPES::ncpft` called :nml:mem:`JULES_INPUT_GRID::cpft_dim_name`. + +.. tabularcolumns:: |p{3.75cm}|p{11cm}| + ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Description | ++============================+===========================================================================================================+ +| ``cropsowdate`` | The sowing date for each crop. | +| | | +| | The sowing date should be a real number, with ``0 < nint(sowing_date) < number of days in year``. | +| | For example, for a 365 day year, sow_date = 1.0 is Jan 1st and sow_date = 365.0 is Dec 31st. | +| | | +| | If a crop requires two sowing dates per year, it should be treated as two separate crops with identical | +| | parameters apart from the sowing date. | +| | | +| | | +| | .. note:: Only required if :nml:mem:`JULES_VEGETATION::l_prescsow` = TRUE. | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``cropttveg`` | Thermal time between emergence and flowering (degree days). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``cropttrep`` | Thermal time between flowering and maturity/harvest (degree days). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``croplatestharvdate`` | The latest possible harvest date for each crop. | +| | croplatestharvdate is only a required variable when | +| | :nml:mem:`JULES_VEGETATION::l_croprotate` = TRUE and | +| | :nml:mem:`JULES_VEGETATION::l_prescsow` = TRUE. | +| | | +| | croplatestharvdate is not a required variable when | +| | :nml:mem:`JULES_VEGETATION::l_croprotate` = FALSE and | +| | :nml:mem:`JULES_VEGETATION::l_prescsow` = TRUE but will be used if provided in the ancillary file | +| | | +| | croplatestharvdate is not a required variable and is only used if provided as an ancillary when | +| | :nml:mem:`JULES_VEGETATION::l_prescsow` = TRUE. | +| | | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ + +.. seealso:: + References: + + * Osborne et al, `JULES-crop: a parametrisation of crops in the Joint UK Land Environment Simulator `_, Geosci. Model Dev., 8, 1139-1155, 2015. + * Mathison et al, 'Developing a sequential cropping capability in the JULESvn5.2 land–surface model', Geosci. Model Dev. Discuss., https://doi.org/10.5194/gmd-2019-85, in review, 2019 + + +``JULES_IRRIG_PROPS`` namelist members +-------------------------------------- + +.. nml:namelist:: JULES_IRRIG_PROPS + +This namelist specifies the options available for initialising irrigated fraction. + +.. nml:member:: read_from_dump + + :type: logical + :default: F + + TRUE + Populate variables associated with this namelist from the dump file. All other namelist members are ignored. + + FALSE + Use the other namelist members to determine how to populate variables. + + +.. nml:member:: read_file + + :type: logical + :default: T + + Indicates if irrigated fraction is to be read from file. + + TRUE + Irrigated fraction is read from the file specified in :nml:mem:`irrig_frac_file`. + + FALSE + Irrigated fraction is set to the constant value specified in :nml:mem:`const_frac_irr`. + + +.. nml:member:: irrig_frac_file + + :type: character + :default: None + + The file from which irrigation fractions are read, including path. + + +.. nml:member:: var_name + + :type: character + :default: 'frac_irig' + + The name of the variable containing the irrigated fraction data. + + .. note:: + This is only used for NetCDF files. + For ASCII files, the irrigated fraction data is expected to be the first (ideally only) variable in the file. + + In the file, the variable must have no levels or time dimensions. + + +.. nml:member:: const_frac_irr + + :type: real + :default: none + + The constant irrigated fraction to be applied to all grid points. + +.. nml:member:: const_irrfrac_irrtiles + + :type: real + :default: none + + The constant irrigated fraction to be applied to specific surface tiles given in :nml:mem:`JULES_IRRIG::irrigtiles`. + + + +``JULES_RIVERS_PROPS`` namelist members +--------------------------------------- + +.. nml:namelist:: JULES_RIVERS_PROPS + +This namelist specifies how spatially varying river routing properties including overbank inundation should be set. + +.. note:: ``read_from_dump`` is not currently implemented for this namelist, meaning that river ancillary variables cannot be read from a dump file. Initial values of river prognostic variables can however be read from a dump file (see :nml:lst:`JULES_INITIAL`). + +.. note:: + The grid on which the river routing will run, and on which river routing ancillaries must be provided, could potentially differ from the input/model grid specified in :doc:`model_grid.nml`. + + For the duration of this section, the following nomenclature will be used: + + * **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). + + The river routing input grid must always be defined on a 2D grid, as defined through the x and y dimensions of the rivers ancillary file (see :nml:mem:`x_dim_name` and :nml:mem:`y_dim_name` for further details). If the model input is defined on a 1D grid, those points must be a subset of a regular grid (meaning one with constant spacing of points in each of the 2 dimensions) if river routing is to be activated. + + JULES calculates runoff on the land grid and this information is then transferred to the river grid by either regridding (when the grids are not coincident) or remapping (between coincident grids). Here coincident means grids of the same resolution and for which points in each grid coincide. Hence land and river grids of different resolution are linked through regridding (interpolation), while a simpler remapping can be used when the gridboxes coincide. Note that functionality to regrid only currently exists for grids that are defined by latitude and longitude coordinates; all other coordinate systems have to be handled through remapping. + + Internally JULES converts the river routing input grid to a 1D river routing model grid, with length ``np_rivers``, which is the number of valid routing points in the domain of interest. All river routing output is either defined on the 1D river routing model grid or is regridded to the land grid. + + The most satisfactory situation is one in which the areas covered by land and river gridboxes are identical (though the resolutions can differ). In that case all the runoff that is generated on the land is correctly captured by the river network, and each river length has a well-defined input of local runoff. However there are situations in which the user might be prepared to allow other configurations - e.g. if studying a particular catchment, land in headwaters of surrounding catchments might not be covered by the river ancillary. + + + +.. nml:group:: Members used to define the river routing input grid + + + .. nml:member:: coordinate_file + + :type: character + :default: None + + The file from which to read coordinate information for the river routing input grid. This is only used when :nml:mem:`file` includes :doc:`variable-name templating ` or when :nml:mem:`read_list` = TRUE, i.e. it is only used when ancillary variables will come from multiple files, in which case this variable is used to provide clarity as to where the coordinates are read from. + + + .. nml:member:: x_dim_name + + :type: character + :default: None + + The name of the x dimension for the river routing input grid (it may, but does not have to, be the same as :nml:mem:`JULES_INPUT_GRID::x_dim_name`). The coordinate system used to define the river input grid must be the same as that used for the main model grid - see :nml:mem:`JULES_LATLON::l_coord_latlon`. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should be the name of the dimension in :nml:mem:`file` (if that does not include :doc:`variable-name templating `) or in :nml:mem:`coordinate_file` (if :nml:mem:`file` includes templating). + .. note:: Values for the coordinates along the x dimension of the river routing input grid will be read from the input file to define the river grid, and it is assumed that the file contains a variable with the same name as the dimension (x_dim_name). + + + .. nml:member:: y_dim_name + + :type: character + :default: None + + The name of the y dimension for the river routing input grid (it may, but does not have to, be the same as :nml:mem:`JULES_INPUT_GRID::y_dim_name`). The coordinate system used to define the river input grid must be the same as that used for the main model grid - see :nml:mem:`JULES_LATLON::l_coord_latlon`. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should be the name of the dimension in :nml:mem:`file` (if that does not include :doc:`variable-name templating `) or in :nml:mem:`coordinate_file` (if :nml:mem:`file` includes templating). + .. note:: Values for the coordinates along the y dimension of the river routing input grid will be read from the input file to define the river grid, and it is assumed that the file contains a variable with the same name as the dimension (y_dim_name). + + .. nml:member:: nx_rivers + + :type: integer + :permitted: >= 2 + :default: None + + The size of the x dimension of the river routing input grid. + + .. nml:member:: ny_rivers + + :type: integer + :permitted: >= 2 + :default: None + + The size of the y dimension of the river routing input grid. + + +.. nml:member:: l_find_grid + + :type: logical + :default: none + + Switch controlling how characteristics of the land grid and the river domain are determined. + + 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. + + 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). + + +.. nml:group:: Members used to describe the land grid + + .. nml:member:: land_dx + + :type: real + :default: None + :permitted: > 0 + + The gridbox size in the x 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:: land_dy + + :type: real + :default: None + :permitted: > 0 + + 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:group:: Only used with l_find_grid = FALSE + + .. nml:member:: nx_land_grid + + :type: integer + :permitted: >= 1 + :default: none + + 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. + + .. 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`. + + .. 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: 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). + +Grids are considered consistent (and therefore regridding is not required) if they are of the same resolution and points on one coincide with points on the other. We do not require that all locations have to be in both grids (though that is desirable), nor do the points need to be presented in the same order in both grids. + + TRUE + River routing and land grids differ and regridding is required. + + FALSE + River routing and land grids are consistent and regridding is not required. + +.. note:: + In principle consistent grids with the same resolution can be handled via regridding, but the recommended approach in that case is to use the simpler remapping. + +.. warning:: + Currently, regridding between land and river routing grids must only be used with regular lat/lon grids. + + If a 1D model input grid is specified in :nml:lst:`JULES_INPUT_GRID`, it must be possible to define a 2D regular lat/lon grid containing all the points in the model input grid. + + An example with the GSWP2 (land points only) forcing data is given below. + + +.. nml:member:: rivers_length + + :type: real + :default: None + + The constant size of the rivers grid (m). This value is used in several ways, as explained below. + + If the coordinate system used is not latitude and longitude (:nml:mem:`JULES_LATLON::l_coord_latlon` = F) river_length must be provided and its value must be >0. This is used to calculate gridbox areas, assuming square gridboxes. + + If the coordinate system used is latitude and longitude, and a run is using RFM (:nml:mem:`JULES_RIVERS::i_river_vn` = 2) and/or overbank inundation without hypsometry (:nml:mem:`JULES_OVERBANK::l_riv_overbank` = T and :nml:mem:`JULES_OVERBANK::overbank_model` = 1 or 2), rivers_length is again required, but in this case a value <= 0 can be used to trigger calculation of a value based on the latitudinal size of gridboxes (this is so as to mimic the behaviour of older versions of the code). In these cases rivers_length is used as a length scale (the distance between points) for RFM and as a length scale (relative to a gridbox) for overbank inundation. + + +.. nml:group:: Members only used with RFM (:nml:mem:`JULES_RIVERS::i_river_vn` = 2). + + .. nml:member:: l_use_area + + :type: logical + :default: F + + Switch to control whether a drainage area ancillary field is used to distinguish between land and river points (for the purpose of setting routing parameter values). + + TRUE + An ancillary field will be used to define the area draining to each point. See "area" in :ref:`list-of-rivers-params`. + + FALSE + No ancillary field will be used and all points will be given river parameter values. + + +.. nml:group:: Members used to determine how river routing and overbank inundation variables are set. + + .. nml:member:: read_list + + :type: logical + :default: F + + Switch controlling how ancillary file names are determined. + + TRUE + Use list of file names; one per line for each of :nml:mem:`nvars`. Files in list cannot use :doc:`variable name templating `. + + FALSE + Use a single file for variables or use variable name template. + + For an example where :nml:mem:`read_list` = TRUE, please see the ``OASIS_RIVERS`` :ref:`Example of coupling request`. + + + .. nml:member:: file + + :type: character + :default: None + + The file (or list of files) from which to read the river routing & overbank inundation properties. + + If :nml:mem:`read_list` is TRUE, this is the file from which to read the list of file names; one per line for each of :nml:mem:`nvars` variables. The file names cannot use :doc:`variable name templating `. If :nml:mem:`use_file` is FALSE for a particular variable, the line may contain ''. + + If :nml:mem:`read_list` is FALSE, this is the file or :doc:`file name template `. + + If :nml:mem:`use_file` is FALSE for every variable, this will not be used. + + + .. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of river routing and overbank inundation property variables that will be provided (see :ref:`list-of-rivers-params`). + + + .. nml:member:: var + + :type: character(nvars) + :default: None + + List of river routing and overbank inundation variable names as recognised by JULES (see :ref:`list-of-rivers-params`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + + + .. nml:member:: use_file + + :type: logical(nvars) + :default: T + + For each JULES variable specified in :nml:mem:`var`, this indicates if it should be read from the specified file or whether a constant value is to be used. + + TRUE + The variable will be read from the file. + + FALSE + The variable will be set to a constant value everywhere using :nml:mem:`const_val` below. + + + .. nml:member:: is_climatology + + :type: logical(nvars) + :default: F + + For each JULES variable specified in :nml:mem:`var`, this indicates if the file is a 12-month climatology. + + TRUE + The file is a 12-month climatology 16th January - 16th December. + + FALSE + The file does not contain a time dimension. + + .. note:: Currently this is only fully implemented for ``rivers_storage``. This allows ``rivers_sto_rp`` to be initialised from a 12-month climatology ancillary on the 2D Rivers grid. When ``rivers_storage`` is initialised in this way, ``rivers_sto_rp`` should not be read from the dump (i.e. should not be requested via :nml:lst:`JULES_INITIAL`). It can be extended to other variables, should this be desirable, but it requires some code changes. + + .. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = TRUE, this is the name of the variable in the file containing the data. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + This is not used for variables where :nml:mem:`use_file` = FALSE, but a placeholder must still be given in that case. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + + + .. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name in place of the variable name substitution string. + + If the file name does not use variable name templating, this is not used. + + + .. nml:member:: const_val + + :type: real(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = FALSE, this is a constant value that the variable will be set to at every point. + + This is not used for variables where :nml:mem:`use_file` = TRUE, but a placeholder must still be given in that case. + + +.. _list-of-rivers-params: + +List of rivers and overbank indundation properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following table summarises river routing properties required to run RFM or TRIP river routing algorithms and overbank inundation properties, specified from an ancillary file if :nml:mem:`JULES_RIVERS_PROPS::use_file` = TRUE. + +.. tabularcolumns:: |p{2.5cm}|L| + ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Description | ++============================+===========================================================================================================+ +| ``area`` | Drainage area (in number of grid boxes) draining into a given grid box. | +| | | +| | This is used with RFM (:nml:mem:`JULES_RIVERS::i_river_vn` = ``2``) to distinguish between river and land | +| | points using the :nml:mem:`JULES_RIVERS::a_thresh` parameter. Points with drainage area > | +| | :nml:mem:`JULES_RIVERS::a_thresh` are treated as rivers, all others as land. These two classes of points | +| | use different wave speeds (e.g. :nml:mem:`JULES_RIVERS::cland` and :nml:mem:`JULES_RIVERS::criver`). | +| | Note that these "river" and "land" classes together comprise the total number of river routing points. | +| | | +| | If this field is not available, all points are treated as rivers. | +| | | +| | The drainage area does not include the grid point itself, and so an extra point must be added where | +| | catchment area calculations are required. | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``direction`` | Flow direction for each river routing grid box, defining the next grid box into which surface or | +| | sub-surface water will be routed. | +| | | +| | This is specified as an integer according to ``[1 = N, 2 = NE, 3 = E, 4 = SE, 5 = S, 6 = SW, 7 = W, | +| | 8 = NW]``. | +| | | +| | Although these are referred to via compass directions, they are used as "grid-relative" directions. | +| | e.g. "N" means "same column, one row up", "E" means "one column over, same row". | +| | Thus for a rotated grid (columns do not run S-N on the Earth), the point "same column, one row up" does | +| | does not lie immediately N. | +| | | +| | Additionally, | +| | | +| | 9: river mouth (outflow to sea) | +| | | +| | 10: inland drainage point (an endorheic catchment; no outflow from grid box) | +| | | +| | All other values (<1 or >10) are excluded from the river calculations (effectively treated as sea). | +| | | +| | Note that at present any river flow at an inland drainage point is NOT added to the soil moisture (in | +| | standalone JULES). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``sequence`` | River routing network pathway number. | +| | | +| | Used by TRIP river routing only (i.e. :nml:mem:`JULES_RIVERS::i_river_vn` = ``1,3``). | +| | See Oki et al. (1999) for details. | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``latitude_2d`` | The latitude of each river grid point must be specified. This field is required only if the model | +| | coordinates are latitude and longitude, i.e. if :nml:mem:`JULES_LATLON::l_coord_latlon` = FALSE. | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``longitude_2d`` | The longitude of each river grid point must be specified. This field is required only if the model | +| | coordinates are latitude and longitude, i.e. if :nml:mem:`JULES_LATLON::l_coord_latlon` = FALSE. | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``logn_mean`` | Mean of ln(elevation-elev_min) for each grid cell (in units ln(m)) | +| | | +| | This is only used if :nml:mem:`JULES_OVERBANK::overbank_model` = 3. | +| | | +| | Note that elev_min is DEM minimum, not river/lake bed level (therefore large values close to water | +| | bodies can occur in floodplain gridcells). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``logn_stdev`` | Standard deviation of ln(elevation-elev_min) for each grid cell (in units ln(m)) | +| | | +| | This is only used if :nml:mem:`JULES_OVERBANK::overbank_model` = 3. | +| | | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``rivers_outflow_number`` | Number assigned to each river mouth and inland basin on the Rivers grid, to identify the river which | +| | discharges into it. | +| | | +| | The river outflow number is used in the calculation of | +| | 'outflow_per_river' (River outflow into the ocean for each river; kg s\ :sup:`-1`) | +| | | +| | This can either be requested 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. | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``rivers_storage`` | Water storage (kg) on the Rivers grid. | +| | | +| | This is only used if :nml:mem:`JULES_RIVERS::i_river_vn` = 3. | +| | | +| | This is only required if Rivers storage is to be initialised from an ancillary, including a 12-month | +| | climatology, rather than the dump. If Rivers storage is requested from an ancillary then | +| | ``rivers_sto_rp`` should not be requested via :nml:lst:`JULES_INITIAL`. | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ + + +Example of how to set up the river grid +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following gives an example of how you would set up the namelists to use routing with the GSWP2 forcing data. + +The model input grid is the GSWP2 grid, i.e. a land-points-only, 1D grid where points lie on a 1\ |deg| x 1\ |deg| grid. The river routing input grid is a 2D 1\ |deg| x 1\ |deg| grid. + +Since both grids are 1\ |deg| x 1\ |deg|, we define the 2D regular lat-lon grid containing the land points to be the river routing input grid, which means we don't need any regridding of variables. :: + + &JULES_INPUT_GRID + grid_is_1d = T, + npoints = 15238, + grid_dim_name = "land" + # ... + / + + &JULES_LATLON + l_coord_latlon = T, + / + + &JULES_RIVERS_PROPS + # Define the river routing input grid + x_dim_name = "longitude", + nx_rivers = 360, + y_dim_name = "latitude", + ny_rivers = 180, + + # Define the 2D regular lat-lon grid containing the model input grid to be a 2D 1\ |deg| x 1\ |deg| grid + nx_land_grid = 360, + ny_land_grid = 180, + x1_land_grid = -179.5, + y1_land_grid = -89.5, + land_dx = 1.0, + land_dy = 1.0, + + # No regridding required since the river routing input grid and the land grid are consistent grids with the same resolution + rivers_regrid = F + / + + +.. |deg| unicode:: U+00B0 + + + +.. seealso:: + References: + + * Appx B of Lewis HW, Castillo Sanchez JM, Graham J, Saulter A, Bornemann J, Arnold A, Fallmann J, Harris C, Pearson D, Ramsdale S, Martínez de la Torre A, Bricheno L, Blyth E, Bell VA, Davies H, Marthews TR, O'Neill C, Rumbold H, O'Dea E, Brereton A, Guihou K, Hines A, Butenschon M, Dadson SJ, Palmer T, Holt J, Reynard N, Best M, Edwards J & Siddorn J (2018). The UKC2 regional coupled environmental prediction system. Geoscientific Model Development 11:1-42. + * Bell, V.A. et al. (2007) Development of a high resolution grid-based river flow model for use with regional climate model output. Hydrology and Earth System Sciences. 11 532-549 + * Oki, T., et al (1999) Assessment of annual runoff from land surface models using Total Runoff Integrating Pathways (TRIP). Journal of the Meteorological Society of Japan. 77 235-255 + + +``JULES_WATER_RESOURCES_PROPS`` namelist members +------------------------------------------------ + +.. nml:namelist:: JULES_WATER_RESOURCES_PROPS + +This namelist specifies how the water resource ancillary properties should be set. + +.. nml:group:: Members used to determine how water resource variables are set + + + .. nml:member:: read_from_dump + + :type: logical + :default: F + + TRUE + Populate variables associated with this namelist from the dump file. All other namelist members are ignored. + + FALSE + Use the other namelist members to determine how to populate variables. + + .. nml:member:: read_list + + :type: logical + :default: F + + Switch controlling how ancillary file names are determined. + + TRUE + Use list of file names; one per line for each of :nml:mem:`nvars`. Files in list cannot use :doc:`variable name templating `. + + FALSE + Use a single file for variables or use variable name template. + + For an example where :nml:mem:`read_list` = TRUE, please see the ``OASIS_RIVERS`` :ref:`Example of coupling request`. + + + .. nml:member:: file + + :type: character + :default: None + + The file (or list of files) from which to read the water resource ancillary properties. + + If :nml:mem:`read_list` is TRUE, this is the file from which to read the list of file names; one per line for each of :nml:mem:`nvars` variables. The file names cannot use :doc:`variable name templating `. If :nml:mem:`use_file` is FALSE for a particular variable, the line may contain ''. + + If :nml:mem:`read_list` is FALSE, this is the file or :doc:`file name template `. + + If :nml:mem:`use_file` is FALSE for every variable, this will not be used. + + + .. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of water resource property variables that will be provided (see :ref:`list-of-water-resources-params`). + + + .. nml:member:: var + + :type: character(nvars) + :default: None + + List of water resource variable names as recognised by JULES (see :ref:`list-of-water-resources-params`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + + + .. nml:member:: use_file + + :type: logical(nvars) + :default: T + + For each JULES variable specified in :nml:mem:`var`, this indicates if it should be read from the specified file or whether a constant value is to be used. + + TRUE + The variable will be read from the file. + + FALSE + The variable will be set to a constant value everywhere using :nml:mem:`const_val` below. + + + .. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = TRUE, this is the name of the variable in the file containing the data. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + This is not used for variables where :nml:mem:`use_file` = FALSE, but a placeholder must still be given in that case. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + + + .. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name in place of the variable name substitution string. + + If the file name does not use variable name templating, this is not used. + + + .. nml:member:: const_val + + :type: real(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = FALSE, this is a constant value that the variable will be set to at every point. + + This is not used for variables where :nml:mem:`use_file` = TRUE, but a placeholder must still be given in that case. + +.. _list-of-water-resources-params: + +List of water resources properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following table summarises ancillary fields for the water resources code, specified from an ancillary file if :nml:mem:`JULES_WATER_RESOURCES_PROPS::use_file` = TRUE. + +.. tabularcolumns:: |p{3cm}|L| + ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Description | ++============================+===========================================================================================================+ +| ``conv_loss_frac`` | Fraction of abstracted water that is lost during conveyance from source to user. | +| | | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``sfc_water_frac`` | Target for the fraction of demand that will be met from surface water (rather than groundwater). | +| | This is only used if :nml:mem:`JULES_WATER_RESOURCES::partition_method` = 1. | +| | | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ + + + +``URBAN_PROPERTIES`` namelist members +------------------------------------- + +.. nml:namelist:: URBAN_PROPERTIES + + +.. nml:member:: read_list + + :type: logical + :default: F + + Switch controlling how ancillary file names are determined. + + TRUE + Use list of file names; one per line for each of :nml:mem:`nvars`. Files in list cannot use :doc:`variable name templating `. + + FALSE + Use a single file for variables or use variable name template. + + For an example where :nml:mem:`read_list` = TRUE, please see the ``OASIS_RIVERS`` :ref:`Example of coupling request`. + + +.. nml:member:: file + + :type: character + :default: None + + The file (or list of files) from which to read the urban properties. + + If :nml:mem:`read_list` is TRUE, this is the file from which to read the list of file names; one per line for each of :nml:mem:`nvars` variables. The file names cannot use :doc:`variable name templating `. If :nml:mem:`use_file` is FALSE for a particular variable, the line may contain ''. + + If :nml:mem:`read_list` is FALSE, this is the file or :doc:`file name template `. + + If :nml:mem:`use_file` is FALSE for every variable, this will not be used. + + +.. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of urban property variables that will be provided. + + The required variables depend on whether MORUSES is used or not: + + * If MORUSES is on, all variables must be given. However, depending on the configuration of MORUSES, not all given variables will be used. Those that will not be used could be set to constant values to avoid setting them from file. + * If MORUSES is *not* on, only ``wrr`` is required. + + +.. nml:member:: var + + :type: character(nvars) + :default: None + + List of urban property variable names as recognised by JULES (see :ref:`list-of-urban-properties`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + + +.. nml:member:: use_file + + :type: logical(nvars) + :default: T + + For each JULES variable specified in :nml:mem:`var`, this indicates if it should be read from the specified file or whether a constant value is to be used. + + TRUE + The variable will be read from the file. + + FALSE + The variable will be set to a constant value everywhere using :nml:mem:`const_val` below. + + +.. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = TRUE, this is the name of the variable in the file containing the data. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + This is not used for variables where :nml:mem:`use_file` = FALSE, but a placeholder must still be given. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + + +.. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name in place of the variable name substitution string. + + If the file name does not use variable name templating, this is not used. + + +.. nml:member:: const_val + + :type: real(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = FALSE, this is a constant value that the variable will be set to at every point in every layer. + + This is not used for variables where :nml:mem:`use_file` = TRUE, but a placeholder must still be given. + + +.. _list-of-urban-properties: + +List of urban properties +~~~~~~~~~~~~~~~~~~~~~~~~ + +All of the urban property variables listed below are expected to have no levels dimensions and no time dimension. + ++---------------+----------------------------------+-------------------------------------------------------------------------------------+ +| Variable name | Description [#]_ | Notes | ++===============+==================================+=====================================================================================+ +| ``wrr`` | Repeating width ratio (or canyon | If :nml:mem:`JULES_URBAN::l_urban_empirical` = TRUE | +| | fraction, W/R) | then this is updated with calculated values. | ++---------------+----------------------------------+-------------------------------------------------------------------------------------+ +| **The following apply to MORUSES only** | ++---------------+----------------------------------+-------------------------------------------------------------------------------------+ +| ``hwr`` | Height-to-width ratio (H/W) | See for ``wrr`` above. | ++---------------+----------------------------------+-------------------------------------------------------------------------------------+ +| ``hgt`` | Building height (H) | See for ``wrr`` above. | ++---------------+----------------------------------+-------------------------------------------------------------------------------------+ +| ``ztm`` | Effective roughness length of | If :nml:mem:`JULES_URBAN::l_moruses_macdonald` = TRUE | +| | urban areas | then this is updated with calculated values. | ++---------------+----------------------------------+-------------------------------------------------------------------------------------+ +| ``disp`` | Displacement height | See for ``ztm`` above. | ++---------------+----------------------------------+-------------------------------------------------------------------------------------+ +| ``albwl`` | Wall albedo | Data only used if :nml:mem:`JULES_URBAN::l_moruses_albedo` = TRUE. | ++---------------+----------------------------------+-------------------------------------------------------------------------------------+ +| ``albrd`` | Road albedo | See for ``albwl`` above. | ++---------------+----------------------------------+-------------------------------------------------------------------------------------+ +| ``emisw`` | Wall emissivity | Data only used if :nml:mem:`JULES_URBAN::l_moruses_emissivity` = TRUE. | ++---------------+----------------------------------+-------------------------------------------------------------------------------------+ +| ``emisr`` | Road emissivity | See for ``emisw`` above. | ++---------------+----------------------------------+-------------------------------------------------------------------------------------+ + + + +.. rubric:: Footnotes + +.. [#] For more information on the urban geometry used please see the JULES technical documentation. + + + +``JULES_CO2`` namelist members +------------------------------ + +.. nml:namelist:: JULES_CO2 + +.. nml:member:: read_from_dump + + :type: logical + :default: F + + TRUE + Populate variables associated with this namelist from the dump file. All other namelist members are ignored. + + FALSE + Use the other namelist members to determine how to populate variables. + + +.. nml:member:: co2_mmr + + :type: real + :default: 5.241e-4 + + Concentration of atmospheric CO2, expressed as a mass mixing ratio. + + +``JULES_FLAKE`` namelist members +-------------------------------- + +.. nml:namelist:: JULES_FLAKE + +.. nml:member:: read_from_dump + + :type: logical + :default: F + + TRUE + Populate variables associated with this namelist from the dump file. All other namelist members are ignored. + + FALSE + Use the other namelist members to determine how to populate variables. + +.. nml:member:: read_list + + :type: logical + :default: F + + Switch controlling how ancillary file names are determined. + + TRUE + Use list of file names; one per line for each of :nml:mem:`nvars`. Files in list cannot use :doc:`variable name templating `. + + FALSE + Use a single file for variables or use variable name template. + + For an example where :nml:mem:`read_list` = TRUE, please see the ``OASIS_RIVERS`` :ref:`Example of coupling request`. + + +.. nml:member:: file + + :type: character + :default: None + + The file (or list of files) from which to read the FLake parameters. + + If :nml:mem:`read_list` is TRUE, this is the file from which to read the list of file names; one per line for each of :nml:mem:`nvars` variables. The file names cannot use :doc:`variable name templating `. If :nml:mem:`use_file` is FALSE for a particular variable, the line may contain ''. + + If :nml:mem:`read_list` is FALSE, this is the file or :doc:`file name template `. + + If :nml:mem:`use_file` is FALSE for every variable, this will not be used. + + +.. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of FLake variables that will be provided. + (At the moment lake depth is the only variable that needs to be provided). + +.. nml:member:: var + + :type: character(nvars) + :default: None + + List of FLake parameter variable names as recognised by JULES (see :ref:`list-of-FLake-params`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + +.. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = TRUE, this is the name of the variable in the file containing the data. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + This is not used for variables where :nml:mem:`use_file` = FALSE, but a placeholder must still be given in that case. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + +.. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name in place of the variable name substitution string. + + If the file name does not use variable name templating, this is not used. + +.. nml:member:: use_file + + :type: logical(nvars) + :default: T + + For each JULES variable specified in :nml:mem:`var`, this indicates if it should be read from the specified file or whether a constant value is to be used. + + TRUE + The variable will be read from the file. + + FALSE + The variable will be set to a constant value everywhere using :nml:mem:`const_val` below. + +.. nml:member:: const_val + + :type: real(nvars) + :default: 5.0m + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = FALSE, this is a constant value that the variable will be set to for every point or gridbox. + + This is not used for variables where :nml:mem:`use_file` = TRUE, but a placeholder must still be given. + + +.. _list-of-FLake-params: + +List of FLake parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabularcolumns:: |p{2.5cm}|L| + ++----------------+---------------------------------------------------------------------------------------+ +| Name | Description | ++================+=======================================================================================+ +| ``lake_depth`` | For each gridbox, the depth of the lakes should be provided in meters. | +| | | +| | Note that for deep lakes FLake will assume an artificial lake bottom at 50m depth. | ++----------------+---------------------------------------------------------------------------------------+ + + +.. _References_ancillaries: + +References for ancillaries +-------------------------- + +* Kattge, J. and Knorr, W., 2007, + Temperature acclimation in a biochemical model of photosynthesis: + a reanalysis of data from 36 species, + Plant, Cell and Environment, 30: 1176--1190, + https://doi.org/10.1111/j.1365-3040.2007.01690.x. diff --git a/doc/source/namelists/cable_pftparm.nml.rst b/doc/source/namelists/cable_pftparm.nml.rst new file mode 100644 index 00000000..cb31433e --- /dev/null +++ b/doc/source/namelists/cable_pftparm.nml.rst @@ -0,0 +1,413 @@ +``cable_pftparm.nml`` +===================== + +This file sets the time and space-invariant parameters for plant functional types for the CABLE land surface model. It contains one namelist called :nml:lst:`CABLE_PFTPARM`. + +``CABLE_PFTPARM`` namelist members +----------------------------------- + +.. nml:namelist:: CABLE_PFTPARM + +This namelist reads the values of parameters for each of the plant functional types (PFTs) if the CABLE land surface model is being used. These parameters are a function of PFT only. Every member must be given a value for every run. +CABLE uses the same parameters for veg and non-veg surface types, unlike JULES, and therefore its arrays are of dimension (npft + nnvg). + +.. nml:member:: a1gs_io + + :type: real(npft + nnvg) + :default: MDI + + Represents the sensitivity of stomatal conductance to the assimilation rate (unitless). + +.. nml:member:: alpha_io + + :type: real(npft + nnvg) + :default: MDI + + Initial slope of J-Q response curve. Units: mol (electrons) mol\ :sup:`-1` (photons) (C3) + mol (CO\ :sub:`2`) mol\ :sup:`-1` (photons) (C4) + +.. nml:member:: canst1_io + + :type: real(npft + nnvg) + :default: MDI + + Maximum intercepted water by canopy. (mm LAI\ :sup:`-1`) + +.. nml:member:: cfrd_io + + :type: real(npft + nnvg) + :default: MDI + + Ratio of day respiration to vcmax + +.. nml:member:: clitt_io + + :type: real(npft + nnvg) + :default: MDI + + Leaf litter (alters resistance to soil evaporation) (tC ha\ :sup:`-1`) + +.. nml:member:: conkc0_io + + :type: real(npft + nnvg) + :default: MDI + + Michaelis-menton constant for carboxylase (bar) + +.. nml:member:: conko0_io + + :type: real(npft + nnvg) + :default: MDI + + Michaelis-menton constant for oxygenase (bar) + +.. nml:member:: convex_io + + :type: real(npft + nnvg) + :default: MDI + + Convexity of J-Q response curve (unitless). + +.. nml:member:: cplant1_io + + :type: real(npft + nnvg) + :default: MDI + + Plant carbon in 1st vegetation carbon store (g C m\ :sup:`-2`) + +.. nml:member:: cplant2_io + + :type: real(npft + nnvg) + :default: MDI + + Plant carbon in 2nd vegetation carbon store (g C m\ :sup:`-2`) + +.. nml:member:: cplant3_io + + :type: real(npft + nnvg) + :default: MDI + + Plant carbon in 3rd vegetation carbon store (g C m\ :sup:`-2`) + +.. nml:member:: csoil1_io + + :type: real(npft + nnvg) + :default: MDI + + Soil carbon in 1st soil carbon store (g C m\ :sup:`-2`) + +.. nml:member:: csoil2_io + + :type: real(npft + nnvg) + :default: MDI + + Soil carbon in 2nd soil carbon store (g C m\ :sup:`-2`) + +.. nml:member:: d0gs_io + + :type: real(npft + nnvg) + :default: MDI + + d0 in stomatal conductance model (kPa) + +.. nml:member:: ejmax_io + + :type: real(npft + nnvg) + :default: MDI + + Maximum potential electron transport rate top leaf, currently double the assigned value of vcmax. (mol m\ :sup:`-2` s\ :sup:`-1`) + +.. nml:member:: ekc_io + + :type: real(npft + nnvg) + :default: MDI + + Activation energy for carboxylase (J mol\ :sup:`-1`) + +.. nml:member:: eko_io + + :type: real(npft + nnvg) + :default: MDI + + Activation energy for oxygenase (J mol\ :sup:`-1`) + +.. nml:member:: extkn_io + + :type: real(npft + nnvg) + :default: MDI + + Extinction coefficient for vertical profile of N. + +.. nml:member:: frac4_io + + :type: real(npft + nnvg) + :default: MDI + + Fraction of c4 plants + +.. nml:member:: froot1_io + + :type: real(npft + nnvg) + :default: MDI + + Fraction of root in 1st soil layer. + +.. nml:member:: froot2_io + + :type: real(npft + nnvg) + :default: MDI + + Fraction of root in 2nd soil layer. + +.. nml:member:: froot3_io + + :type: real(npft + nnvg) + :default: MDI + + Fraction of root in 3rd soil layer. + +.. nml:member:: froot4_io + + :type: real(npft + nnvg) + :default: MDI + + Fraction of root in 4th soil layer. + +.. nml:member:: froot5_io + + :type: real(npft + nnvg) + :default: MDI + + Fraction of root in 5th soil layer. + +.. nml:member:: froot6_io + + :type: real(npft + nnvg) + :default: MDI + + Fraction of root in 6th soil layer. + +.. nml:member:: g0_io + + :type: real(npft + nnvg) + :default: MDI + + Residual stomatal conductance as net assimilation rate reaches zero (mol m\ :sup:`-2` s\ :sup:`-1`) + +.. nml:member:: g1_io + + :type: real(npft + nnvg) + :default: MDI + + Sensitivity of stomatal conductance to the assimilation rate (kPa). + +.. nml:member:: gswmin_io + + :type: real(npft + nnvg) + :default: MDI + + Minimal stomatal conductance (mol m\ :sup:`-2` s\ :sup:`-1`) + +.. nml:member:: hc_io + + :type: real(npft + nnvg) + :default: MDI + + Height of canopy (m) + +.. nml:member:: lai_io + + :type: real(npft + nnvg) + :default: None + + The leaf area index (LAI) of each PFT. + +.. nml:member:: length_io + + :type: real(npft + nnvg) + :default: MDI + + Leaf length (m) + +.. nml:member:: ratecp1_io + + :type: real(npft + nnvg) + :default: MDI + + Plant carbon pool rate constant in 1st vegetation carbon store (year\ :sup:`-1`). + +.. nml:member:: ratecp2_io + + :type: real(npft + nnvg) + :default: MDI + + Plant carbon pool rate constant in 2nd vegetation carbon store (year\ :sup:`-1`). + +.. nml:member:: ratecp3_io + + :type: real(npft + nnvg) + :default: MDI + + Plant carbon pool rate constant in 3rd vegetation carbon store (year\ :sup:`-1`). + +.. nml:member:: ratecs1_io + + :type: real(npft + nnvg) + :default: MDI + + Soil carbon pool rate constant in 1st soil carbon store (year\ :sup:`-1`). + +.. nml:member:: ratecs2_io + + :type: real(npft + nnvg) + :default: MDI + + Soil carbon pool rate constant in 2nd soil carbon store (year\ :sup:`-1`). + +.. nml:member:: refl1_io + + :type: real(npft + nnvg) + :default: MDI + + Leaf reflectance in 1st radiation band. + +.. nml:member:: refl2_io + + :type: real(npft + nnvg) + :default: MDI + + Leaf reflectance in 2nd radiation band. + +.. nml:member:: refl3_io + + :type: real(npft + nnvg) + :default: MDI + + Leaf reflectance in 3rd radiation band. + +.. nml:member::rootbeta_io + + :type: real(npft + nnvg) + :default: MDI + + Beta parameter (Jackson et al. 1996) to calculate froot + +.. nml:member:: rp20_io + + :type: real(npft + nnvg) + :default: MDI + + Plant respiration scaler + +.. nml:member:: rpcoef_io + + :type: real(npft + nnvg) + :default: MDI + + Temperature coefficient for non-leaf plant respiration (C\ :sup:`-1`) + +.. nml:member:: rs20_io + + :type: real(npft + nnvg) + :default: MDI + + Soil respiration at 20 deg C + +.. nml:member:: shelrb_io + + :type: real(npft + nnvg) + :default: MDI + + Sheltering factor + +.. nml:member:: taul1_io + + :type: real(npft + nnvg) + :default: MDI + + Leaf transmittance in 1st radiation band + +.. nml:member:: taul2_io + + :type: real(npft + nnvg) + :default: MDI + + Leaf transmittance in 2nd radiation band + +.. nml:member:: taul3_io + + :type: real(npft + nnvg) + :default: MDI + + Leaf transmittance in 3rd radiation band + +.. nml:member:: tmaxvj_io + + :type: real(npft + nnvg) + :default: MDI + + Maximum temperature of the start of photosynthesis (deg C) + +.. nml:member:: tminvj_io + + :type: real(npft + nnvg) + :default: MDI + + Minimum temperature of the start of photosynthesis (deg C) + +.. nml:member:: vbeta_io + + :type: real(npft + nnvg) + :default: MDI + + Stomatal sensitivity to soil water. + +.. nml:member:: vcmax_io + + :type: real(npft + nnvg) + :default: MDI + + Maximum RuBP carboxylation rate top leaf. (mol m\ :sup:`-2` s\ :sup:`-1`) + +.. nml:member:: vegcf_io + + :type: real(npft + nnvg) + :default: MDI + + Scalar on soil respiration (place-holder scheme) + +.. nml:member:: wai_io + + :type: real(npft + nnvg) + :default: MDI + + Wood area index (stem + branches + twigs) (not currently used in any calculations) + +.. nml:member:: width_io + + :type: real(npft + nnvg) + :default: MDI + + Leaf width (m) + +.. nml:member:: xalbnir_io + + :type: real(npft + nnvg) + :default: MDI + + Not currently used in any calculations. + +.. nml:member:: xfang_io + + :type: real(npft + nnvg) + :default: MDI + + Leaf angle parameter + +.. nml:member:: zr_io + + :type: real(npft + nnvg) + :default: MDI + + Maximum rooting depth (cm) + diff --git a/doc/source/namelists/cable_prognostics.nml.rst b/doc/source/namelists/cable_prognostics.nml.rst new file mode 100644 index 00000000..c3deb811 --- /dev/null +++ b/doc/source/namelists/cable_prognostics.nml.rst @@ -0,0 +1,126 @@ +``cable_prognostics.nml`` +========================== + + +This file contains a single namelist called :nml:lst:`CABLE_PROGS` that is used to set up the initial state of prognostic variables. + + +``CABLE_PROGS`` namelist members +---------------------------------- + +.. nml:namelist:: CABLE_PROGS + +The values of all prognostic variables must be set at the start of a run. This initial state, or initial condition, can be read from a file. Another option is to prescribe a simple or idealised initial state by giving constant values for the prognostic variables directly in the namelist. It is also possible to set some fields using values from a file but to set others to constants given in the namelist. + + +.. nml:member:: file + + :type: character + :default: None + + The file to read initial values for CABLE prognostic variables from. + + If :nml:mem:`use_file` is FALSE for every variable, this will not be used. + + This file name can use :doc:`variable name templating `. + + +.. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of prognostic variables that will be provided (see :ref:`list-of-cable-prognostic-variables`). + + +.. nml:member:: var + + :type: character(nvars) + :default: None + + List of CABLE prognostic variable names as recognised by CABLE (see :ref:`list-of-cable-prognostic-variables`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + + +.. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each CABLE variable specified in :nml:mem:`var`, this is the string to substitute into the file name in place of the variable name substitution string. + + If the file name does not use variable name templating, this is not used. + + +.. nml:member:: use_file + + :type: logical(nvars) + :default: T + + For each CABLE variable specified in :nml:mem:`var`, this indicates if it should be read from the specified file or whether a constant value is to be used. + + TRUE + The variable will be read from the file. + + FALSE + The variable will be set to a constant value everywhere using :nml:mem:`const_val` below. + + +.. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each CABLE variable specified in :nml:mem:`var` where :nml:mem:`use_file` = TRUE, this is the name of the variable in the file containing the data. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + This is not used for variables where :nml:mem:`use_file` = FALSE, but a placeholder must still be given in that case. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + + +.. nml:member:: const_val + + :type: real(nvars) + :default: None + + For each CABLE variable specified in :nml:mem:`var` where :nml:mem:`use_file` = FALSE, this is a constant value that the variable will be set to at every point in every layer. + + This is not used for variables where :nml:mem:`use_file` = TRUE, but a placeholder must still be given in that case. + + +.. _list-of-cable-prognostic-variables: + +List of CABLE prognostic variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Values are set for each tile of each grid point and for each layer of soil or snow. + +.. tabularcolumns:: |p{5cm}|p{10cm}| + ++-------------------------------+-------------------------------------------------------------------------------+ +| Name | Description | ++===============================+===============================================================================+ +| ``SoilTemp_CABLE`` | Temperature of each soil layer (K). | ++-------------------------------+-------------------------------------------------------------------------------+ +| ``SoilMoisture_CABLE`` | Soil moisture content of each soil layer (kg m\ :sup:`-2`). | ++-------------------------------+-------------------------------------------------------------------------------+ +| ``FrozenSoilFrac_CABLE`` | Frozen soil moisture content of each soil layer as a fraction of saturation. | ++-------------------------------+-------------------------------------------------------------------------------+ +| ``SnowDepth_CABLE`` | Depth of each snow level (m). | ++-------------------------------+-------------------------------------------------------------------------------+ +| ``SnowMass_CABLE`` | Mass of each each snow level (kg). | ++-------------------------------+-------------------------------------------------------------------------------+ +| ``SnowTemp_CABLE`` | Temperature for each snow layer (K). | ++-------------------------------+-------------------------------------------------------------------------------+ +| ``SnowDensity_CABLE`` | Density for each snow layer (kg m\ :sup:`-3`). | ++-------------------------------+-------------------------------------------------------------------------------+ +| ``SnowAge_CABLE`` | Age of each snow layer | ++-------------------------------+-------------------------------------------------------------------------------+ +| ``OneLyrSnowDensity_CABLE`` | Snow density when all snow treated as one layer. (kg m\ :sup:`-3`) | ++-------------------------------+-------------------------------------------------------------------------------+ +| ``ThreeLayerSnowFlag_CABLE`` | Flag for 3 layer snow pack (0 - false, 1 - true) | ++-------------------------------+-------------------------------------------------------------------------------+ \ No newline at end of file diff --git a/doc/source/namelists/cable_soilparm.nml.rst b/doc/source/namelists/cable_soilparm.nml.rst new file mode 100644 index 00000000..017b7f42 --- /dev/null +++ b/doc/source/namelists/cable_soilparm.nml.rst @@ -0,0 +1,104 @@ +``cable_soilparm.nml`` +============================ + + +This file contains a namelist called :nml:lst:`CABLE_SOILPARM` that sets time-invariant parameters for different soil types for the CABLE land surface model. + +``CABLE_SOILPARM`` namelist members +----------------------------------------- + +.. nml:namelist:: CABLE_SOILPARM + + +This namelist reads the values of parameters for each of the soil types if the CABLE land surface model is being used. These parameters are a function of surface type only. All parameters must be defined for any configuration. +The number of soil types is stored in the `n_soiltypes` parameter and for the current version of CABLE is set to `9`. + +.. nml:member:: silt_io + + :type: real(n_soiltypes) + :default: MDI + + Fraction of soil which is silt. + + +.. nml:member:: clay_io + + :type: real(n_soiltypes) + :default: MDI + + Fraction of soil which is clay. + + +.. nml:member:: sand_io + + :type: real(n_soiltypes) + :default: MDI + + Fraction of soil which is sand. + + +.. nml:member:: swilt_io + + :type: real(n_soiltypes) + :default: MDI + + Volume of H\ :sub:`2`\O at wilting (m\ :sup:`3` m\ :sup:`-3`) + + +.. nml:member:: sfc_io + + :type: real(n_soiltypes) + :default: MDI + + Volume of H\ :sub:`2`\O at field capacity (m\ :sup:`3` m\ :sup:`-3`) + + +.. nml:member:: ssat_io + + :type: real(n_soiltypes) + :default: MDI + + Volume of H\ :sub:`2`\O at saturation (m\ :sup:`3` m\ :sup:`-3`) + + +.. nml:member:: bch_io + + :type: real(n_soiltypes) + :default: MDI + + Parameter b in Campbell equation. + + +.. nml:member:: hyds_io + + :type: real(n_soiltypes) + :default: MDI + + Hydraulic conductivity at saturation (m\ :sup:`-1`). + + +.. nml:member:: sucs_io + + :type: real(n_soiltypes) + :default: MDI + + Suction at saturation (m). + + +.. nml:member:: rhosoil_io + + :type: real(n_soiltypes) + :default: MDI + + Soil bulk density (kg m\ :sup:`-3`) + + +.. nml:member:: css_io + + :type: real(n_soiltypes) + :default: MDI + + Soil specific heat capacity (J kg\ :sup:`-1` K\ :sup:`-1`). + + + diff --git a/doc/source/namelists/cable_surface_types.nml.rst b/doc/source/namelists/cable_surface_types.nml.rst new file mode 100644 index 00000000..5fc9edeb --- /dev/null +++ b/doc/source/namelists/cable_surface_types.nml.rst @@ -0,0 +1,73 @@ +``cable_surface_types.nml`` +================================= + + +This file configures the surface types used by CABLE. It contains one namelist called :nml:lst:`CABLE_SURFACE_TYPES`. + + +``CABLE_SURFACE_TYPES`` namelist members +---------------------------------------- + + +.. nml:namelist:: CABLE_SURFACE_TYPES + +.. nml:member:: npft_cable + + :type: integer + :permitted: >= 1 + :default: -32768 + + The number of plant functional types to be modelled. + + +.. nml:member:: nnvg_cable + + :type: integer + :permitted: >= 1 + :default: -32768 + + The number of non-plant surface types to be modelled. + + +.. note:: + The total number of surface types to be modelled is called ``ntype_cable``, and is given by ``ntype_cable = npft_cable + nnvg_cable``. + + In the standard setup, CABLE models 13 vegetation types and 4 non-vegetation types (``npft_cable = 13``, ``nnvg_cable = 4``). However, the model domain need not contain all 13 types, e.g. the domain could consist of a single point with 100% grass. The amount of each type in the domain is normally set in :nml:lst:`JULES_FRAC`. + + +.. nml:member:: urban_drive + + :type: integer + :default: -32768 + + +.. nml:member:: lakes_cable + + :type: integer + :default: -32768 + + Index of the lakes surface type. + + A negative value indicates no lakes surface type. + + +.. nml:member:: barren_cable + + :type: integer + :permitted: >= 1 + :default: -32768 + + Index of the barren soil surface type. + + .. note:: A barren soil surface type must be given. + + +.. nml:member:: ice_cable + + :type: integer + :default: -32768 + + Index of the ice surface type. + + A negative value indicates no ice surface type. + diff --git a/doc/source/namelists/contents.rst b/doc/source/namelists/contents.rst new file mode 100644 index 00000000..bf038a3d --- /dev/null +++ b/doc/source/namelists/contents.rst @@ -0,0 +1,56 @@ +The JULES namelist files +======================== + + +Each run of JULES is controlled by a number of files containing Fortran namelists. These files specify details including: + +* Switches to allow different model configurations to be selected at run-time. +* Start and end times for the run. +* What input data to use and how to read it. +* How to construct the model grid. +* Values for various parameters. +* The required output. + +These files have specific names, and JULES expects all these files to exist for every run (even when their contents are not required). JULES also expects that the namelists within each file appear in the order given below. + + +.. toctree:: + :maxdepth: 2 + + intro + jules_prnt_control.nml + jules_surface_types.nml + cable_surface_types.nml + model_environment.nml + jules_surface.nml + jules_radiation.nml + jules_hydrology.nml + jules_soil.nml + jules_vegetation.nml + jules_soil_biogeochem.nml + jules_soil_ecosse.nml + jules_deposition.nml + jules_snow.nml + jules_rivers.nml + oasis_rivers.nml + jules_water_resources.nml + jules_irrig.nml + science_fixes.nml + timesteps.nml + model_grid.nml + ancillaries.nml + cable_prognostics.nml + pft_params.nml + cable_pftparm.nml + nveg_params.nml + cable_soilparm.nml + crop_params.nml + triffid_params.nml + red_params.nml + urban.nml + fire.nml + drive.nml + imogen.nml + prescribed_data.nml + initial_conditions.nml + output.nml diff --git a/doc/source/namelists/crop_params.nml.rst b/doc/source/namelists/crop_params.nml.rst new file mode 100644 index 00000000..a440caa6 --- /dev/null +++ b/doc/source/namelists/crop_params.nml.rst @@ -0,0 +1,245 @@ +``crop_params.nml`` +=================== + + +This file contains a single namelist called :nml:lst:`JULES_CROPPARM` that sets time- and space-invariant parameters for each crop type. + + +``JULES_CROPPARM`` namelist members +----------------------------------- + +.. nml:namelist:: JULES_CROPPARM + +This namelist reads the values of parameters for each of the crop functional types. These parameters are a function of crop pft only. These parameters are only required if :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0. The crop pfts should be in the same order as in :doc:`pft_params.nml`. + +.. seealso:: + References: + + * Osborne et al, `JULES-crop: a parametrisation of crops in the Joint UK Land Environment Simulator `_, Geosci. Model Dev., 8, 1139-1155, 2015. + + Parameters introduced after the Osborne et al 2015 paper are described in the appendix of + + * Williams et al, `Evaluation of JULES-crop performance against site observations of irrigated maize from Mead, Nebraska `_, Geosci. Model Dev., 10, 1291-1320, 2017. + +.. nml:member:: t_bse_io + + :type: real(ncpft) + :default: None + + Base temperature (K). + + +.. nml:member:: t_opt_io + + :type: real(ncpft) + :default: None + + Optimum temperature (K). + + +.. nml:member:: tmax_io + + :type: real(ncpft) + :default: None + + Maximum temperature (K). + + +.. nml:member:: tt_emr_io + + :type: real(ncpft) + :default: None + + Thermal time between sowing and emergence (deg Cd). + + +.. nml:member:: crit_pp_io + + :type: real(ncpft) + :default: None + + Critical photoperiod (hours). + + +.. nml:member:: pp_sens_io + + :type: real(ncpft) + :default: None + + Sensitivity of development rate to photoperiod (hours\ :sup:`-1`). + + +.. nml:member:: rt_dir_io + + :type: real(ncpft) + :default: None + + Coefficient determining relative growth of roots vertically and horizontally. + + +.. nml:member:: alpha1_io + + :type: real(ncpft) + :default: None + + Coefficient for determining partitioning. + + +.. nml:member:: alpha2_io + + :type: real(ncpft) + :default: None + + Coefficient for determining partitioning. + + +.. nml:member:: alpha3_io + + :type: real(ncpft) + :default: None + + Coefficient for determining partitioning. + + +.. nml:member:: beta1_io + + :type: real(ncpft) + :default: None + + Coefficient for determining partitioning. + + +.. nml:member:: beta2_io + + :type: real(ncpft) + :default: None + + Coefficient for determining partitioning. + + +.. nml:member:: beta3_io + + :type: real(ncpft) + :default: None + + Coefficient for determining partitioning. + + +.. nml:member:: gamma_io + + :type: real(ncpft) + :default: None + + Coefficient for determining specific leaf area (m\ :sup:`2` kg\ :sup:`-1`). + + +.. nml:member:: delta_io + + :type: real(ncpft) + :default: None + + Coefficient for determining specific leaf area (m\ :sup:`2` kg\ :sup:`-1`). + + +.. nml:member:: remob_io + + :type: real(ncpft) + :default: None + + Remobilisation factor. Fraction of stem growth partitioned to RESERVEC. + + +.. nml:member:: cfrac_s_io + + :type: real(npft) + :default: None + + Carbon fraction of dry matter for stems. + + +.. nml:member:: cfrac_r_io + + :type: real(ncpft) + :default: None + + Carbon fraction of dry matter for roots. + + +.. nml:member:: cfrac_l_io + + :type: real(ncpft) + :default: None + + Carbon fraction of dry matter for leaves. + + +.. nml:member:: allo1_io + + :type: real(ncpft) + :default: None + + Allometric coefficient relating STEMC to CANHT. + + +.. nml:member:: allo2_io + + :type: real(ncpft) + :default: None + + Allometric coefficient relating STEMC to CANHT. + + +.. nml:member:: mu_io + + :type: real(ncpft) + :default: None + + Allometric coefficient for calculation of senescence. MIN(mu_io * (dvi - sen_dvi_io) ** nu_io, 1.0) is the fraction of leaf carbon that is moved to the harvest pool per day once senescence has started. + + +.. nml:member:: nu_io + + :type: real(ncpft) + :default: None + + Allometric coefficient for calculation of senescence. See description for :nml:mem:`mu_io` + + +.. nml:member:: yield_frac_io + + :type: real(ncpft) + :default: None + + Fraction of the harvest carbon pool converted to yield carbon (yield is the economically valuable component of the harvest pool e.g. kernel). + + +.. nml:member:: initial_carbon_io + + :type: real(ncpft) + :default: None + + Carbon in crop at emergence in kgC/m2. + + +.. nml:member:: initial_c_dvi_io + + :type: real(ncpft) + :default: None + + DVI at which the crop carbon is set to :nml:mem:`initial_carbon_io`. Should be at emergence (0.0) or shortly after. + + +.. nml:member:: sen_dvi_io + + :type: real(ncpft) + :default: None + + DVI at which leaf senescence begins. + + +.. nml:member:: t_mort_io + + :type: real(ncpft) + :default: None + + Soil temperature (second level) at which to kill crop if DVI>1. diff --git a/doc/source/namelists/drive.nml.rst b/doc/source/namelists/drive.nml.rst new file mode 100644 index 00000000..1672b14a --- /dev/null +++ b/doc/source/namelists/drive.nml.rst @@ -0,0 +1,587 @@ +``drive.nml`` +============= + + +This file contains a single namelist called :nml:lst:`JULES_DRIVE` that indicates how meteorological driving data is input. + + +``JULES_DRIVE`` namelist members +-------------------------------- + +.. nml:namelist:: JULES_DRIVE + +.. nml:member:: t_for_snow + + :type: real + :default: None + + If total precipitation is given as a forcing variable, then :nml:mem:`t_for_snow` is the near-surface air temperature (K) at or below which the precipitation is assumed to be snowfall. At higher temperatures, all the precipitation is assumed to be liquid. The default value used to be 274.0 K. + + +.. nml:member:: t_for_con_rain + + :type: real + :default: None + + If total preciption or total rainfall are given, then :nml:mem:`t_for_con_rain` is the near-surface air temperature (K) at or above which rainfall is assumed to be convective in origin. At lower temperatures, all the rainfall is assumed to be large-scale in origin. In this configuration all snow is assumed to be large-scale in origin. The default value used to be 373.15 K but in general this is not recommended as it effectively means all precipitation is large-scale; a value of 293.15 K might be more appropriate. + + Also see :nml:mem:`JULES_SOIL::confrac`. + + :nml:mem:`t_for_con_rain` is not used if :nml:mem:`JULES_SURFACE::l_point_data` = TRUE, since then there is no convective precipitation. + + +.. nml:member:: diff_frac_const + + :type: real + :default: None + + A constant value used to calculate diffuse radiation from the total downward shortwave radiation. + + Only used if diffuse radiation is not given as a forcing variable (see :ref:`list-of-jules-forcing-variables`). + + +.. nml:group:: Members used to control the daily disaggregator + + HCTN96 refer to Hadley Centre technical note 96, available from `the Met Office Library `_. + + .. nml:member:: l_daily_disagg + + :type: logical + :default: F + + Switch controlling whether the disaggregator is used to convert daily data driving data to driving data at the model timestep. See HCTN96 for a description of the disaggregation methods used. + + TRUE + Disaggregator is used. + + .. warning:: + The disaggregator requires: + + #. Daily forcing data, i.e. :nml:mem:`data_period` = 86400 + #. :nml:mem:`JULES_TIME::main_run_start`, :nml:mem:`JULES_SPINUP::spinup_start` and :nml:mem:`data_start` to be 00:00:00 for some day. + + FALSE + Disaggregator is not used. + + + .. nml:member:: l_disagg_const_rh + + :type: logical + :default: F + + Switch controlling sub-daily disaggregation of humidity. + + Only used if :nml:mem:`l_daily_disagg` = TRUE. + + TRUE + Relative humidity is kept constant over day. + + FALSE + Specific humidity is kept constant over day (apart from when limited by specific humidity at saturation). + + + .. nml:member:: dur_conv_rain + + :type: real + :default: None + + Duration of a convective rainfall event in seconds for use in the disaggregator. See HCTN96 section 2.4. A value of 21600s (6 hours) used to be the default. + + Only used if :nml:mem:`l_daily_disagg` = TRUE. + + + .. nml:member:: dur_ls_rain + + :type: real + :default: None + + Duration of a large-scale rainfall event in seconds for use in the disaggregator. See HCTN96 section 2.4. A value of 3600s (1 hour) used to be the default. + + Only used if :nml:mem:`l_daily_disagg` = TRUE. + + + .. nml:member:: dur_conv_snow + + :type: real + :default: None + + Duration of a convective snowfall event in seconds for use in the disaggregator. See HCTN96 section 2.4. A value of 3600s (1 hour) used to be the default. + + Only used if :nml:mem:`l_daily_disagg` = TRUE. + + + .. nml:member:: dur_ls_snow + + :type: real + :default: None + + Duration of a large-scale snowfall event in seconds for use in the disaggregator. See HCTN96 section 2.4. A value of 3600s (1 hour) used to be the default. + + Only used if :nml:mem:`l_daily_disagg` = TRUE. + + + .. nml:member:: precip_disagg_method + + :type: integer + :permitted: 1, 2, 3 or 4 + :default: None + + Switch controlling the disaggregation method for precipitation. See HCTN96 section 2.4. The default value used to be 2. + + Only used if :nml:mem:`l_daily_disagg` = TRUE. + + 1. Do not disaggregate precipitation. + 2. Disaggregate precipitation using the method implemented in IMOGEN, which allocates the daily precipitation each type into one event of duration :nml:mem:`dur_conv_rain`, :nml:mem:`dur_ls_rain`, :nml:mem:`dur_conv_snow` and :nml:mem:`dur_ls_snow` for convective rain, large-scale rain, convective snow and large-scale snow respectively. + The start time of this event is randomly distributed from the beginning of the day to the end of the day minus the event duration. + If the rate of precipitation in any timestep of any type is greater than a hard-coded maximum (currently 350 mm/day), the precipitation is redistributed by the ``redis`` routine in IMOGEN. + 3. As for 2, except no upper limit on the precipitation in a timestep. + 4. The event duration variable is used to determine the fraction of wet and dry timesteps, which are then distributed randomly throughout the day. + + +.. nml:group:: Members used to specify perturbations to the driving data + + .. nml:member:: l_perturb_driving + + :type: logical + :default: F + + Apply perturbation to driving data. + + .. nml:member:: temperature_abs_perturbation + + :type: real + :default: None + + Absolute perturbation amount to add to temperature. Can be positive or negative. Only used if :nml:mem:`l_perturb_driving` = TRUE. + + .. nml:member:: precip_rel_perturbation + + :type: real + :permitted: >= 0.0 + :default: None + + Relative perturbation for precipitation variables (a multiplicative factor). Only used if :nml:mem:`l_perturb_driving` = TRUE. + + +.. nml:group:: Members used to specify ``z1_tq`` and ``z1_uv`` + + .. nml:member:: z1_uv_in + + :type: real + :permitted: > 0.0 + :default: None + + Constant value for the height (m) at which the wind data are valid for every point. This height is relative to the zero-plane, not the ground. + + + .. nml:member:: z1_tq_vary + + :type: logical + :default: F + + Switch to indicate whether ``z1_tq`` (the height (m) at which the temperature and humidity data are valid) should be constant for all points or spatially varying. The height is relative to the zero-plane, not the ground. + + TRUE + Spatially varying ``z1_tq`` will be read from the file specified in :nml:mem:`z1_tq_file`. + + FALSE + ``z1_tq`` will be set to a constant value, specified in :nml:mem:`z1_tq_in`, at all points. + + + .. nml:member:: z1_tq_in + + :type: real + :permitted: > 0.0 + :default: None + + Constant value for ``z1_tq`` to be used for every point. + + Only required if :nml:mem:`z1_tq_vary` = F. + + + .. nml:member:: z1_tq_file + + :type: character + :default: None + + File to read spatially varying ``z1_tq`` from. + + Only required if :nml:mem:`z1_tq_vary` = T. + + + .. nml:member:: z1_tq_var_name + + :type: character + :default: 'z1_tq_in' + + The name of the variable in :nml:mem:`z1_tq_file` containing the data for ``z1_tq``. + + The variable should have no levels dimensions and no time dimension. + + .. note:: + This is not used for ASCII files. + + However, since ASCII files can only be used for single-point runs, it is recommended to set :nml:mem:`z1_tq_vary` = F and use :nml:mem:`z1_tq_in` anyway. + + +.. nml:group:: Members used to specify boundary layer height + + .. nml:member:: bl_height + + :type: real + :permitted: > 0.0 + :default: 1000.0 + + Height above ground to top of the atmospheric boundary layer (m). This value is disregarded if ``bl_height`` is provided as prescribed data (see :ref:`supported-prescribed-variables`). + + +.. nml:group:: Members used to specify the start, end and period of the data + + .. nml:member:: data_start + .. nml:member:: data_end + + :type: character + :default: None + + The times of the start of the first timestep of data and the end of the last timestep of data. + + Each run of JULES (configured in :doc:`timesteps.nml`) can use part or all of the specified data. However, there must be data for all times between run start and run end (determined by :nml:mem:`JULES_TIME::main_run_start`, :nml:mem:`JULES_TIME::main_run_end`, :nml:mem:`JULES_SPINUP::spinup_start` and :nml:mem:`JULES_SPINUP::spinup_end`). + + The times must be given in the format:: + + "yyyy-mm-dd hh:mm:ss" + + + .. nml:member:: data_period + + :type: integer + :permitted: -2, -1 or > 0 + :default: None + + The period, in seconds, of the data. + + Special cases: + + | **-1:** Monthly data + | **-2:** Yearly data + + +.. nml:group:: Members used to specify the files containing the data + + .. nml:member:: read_list + + :type: logical + :default: F + + Switch controlling how data file names are determined for a given time. + + TRUE + Use a list of data file names with times of first data. + + FALSE + Use a single data file for all times or a template describing the names of the data files. + + + .. nml:member:: nfiles + + :type: integer + :permitted: >= 0 + :default: 0 + + Only used if :nml:mem:`read_list` = TRUE. + + The number of data files to read name and time of first data for. + + + .. nml:member:: file + + :type: character + :default: None + + If :nml:mem:`read_list` = TRUE, this is the file to read the list of data file names and times from. Each line should be of the form:: + + '/data/file', 'yyyy-mm-dd hh:mm:ss' + + In this case data file names may contain variable name templating only, with the proviso that either no file names use variable name templating or all file names do. The files must appear in chronological order. + + If :nml:mem:`read_list` = FALSE, this is either the single data file (if no templating is used) or a template for data file names. Both :doc:`time and variable name templating ` may be used. + + +.. nml:group:: Members used to specify the provided variables + + .. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of forcing variables that will be provided. + + See :ref:`list-of-jules-forcing-variables` for the available forcing variables and their possible configurations. + + + .. nml:member:: var + + :type: character(nvars) + :default: None + + List of forcing variable names as recognised by JULES (see :ref:`list-of-jules-forcing-variables`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + + + .. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each JULES variable specified in :nml:mem:`var`, this is the name of the variable in the file(s) containing the data. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + + + .. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name(s) in place of the variable name substitution string. + + If the file name(s) do not use variable name templating, this is not used. + + + .. nml:member:: interp + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this indicates how the variable is to be interpolated in time (see :doc:`/input/temporal-interpolation`). + + +.. _list-of-jules-forcing-variables: + +List of JULES forcing variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All of the available forcing variables listed in the sections below, are expected to have no levels dimensions, but must have a time dimension called :nml:mem:`JULES_INPUT_GRID::time_dim_name`. + +Pressure, Humidity and Temperature +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Description | ++============================+===========================================================================================================+ +| ``pstar`` | Air pressure (Pa). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``q`` | Specific humidity (kg kg\ :sup:`-1`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``t`` | Air temperature (K). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ + +Radiation variables +^^^^^^^^^^^^^^^^^^^ + +The radiation forcing variables can be given in one of four ways: + +``sw_down`` and ``lw_down`` + Downward fluxes of short- and longwave radiation are input. *This is the preferred option.* + +``rad_net`` and ``sw_down`` + Downward shortwave and net all wavelength (downward is positive) radiation are input. The modelled albedo and surface temperature are used to calculate the downward longwave flux. + +``lw_net`` and ``sw_net`` + Net downward fluxes of short- and longwave radiation are input. The modelled albedo and surface temperature are used to calculate the downward fluxes of shortwave and longwave radiation. + +``lw_down`` and ``sw_net`` + Downward flux of longwave radiation and net downward flux of shortwave radiation are input. The modelled albedo is used to calculate the downward flux of shortwave radiation. + +If any of the four combinations of radiation variables listed above are provided, then these are used to drive JULES. There is no default option. JULES will give a fatal error and stop if there are too many, too few or invalid forcing variables provided in the variable list. + +.. warning:: If :nml:mem:`l_daily_disagg` = TRUE, then the first method must be used. + +``diff_rad`` can be used with any of the four methods. If it is given, diffuse radiation is input from file. If it is not given, :nml:mem:`JULES_DRIVE::diff_frac_const` is used instead to partition the downward shortwave radiation into diffuse and direct. + ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Description | ++============================+===========================================================================================================+ +| ``rad_net`` | Net (all wavelength) downward radiation (W m\ :sup:`-2`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``lw_net`` | Net downward longwave radiation (W m\ :sup:`-2`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``sw_net`` | Net downward shortwave radiation (W m\ :sup:`-2`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``lw_down`` | Downward longwave radiation (W m\ :sup:`-2`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``sw_down`` | Downward shortwave radiation (W m\ :sup:`-2`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``diff_rad`` | Diffuse radiation (W m\ :sup:`-2`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ + +Precipitation variables +^^^^^^^^^^^^^^^^^^^^^^^ + +The precipitation variables can be specified in one of four ways: + +``precip`` + A single precipitation field is input. This represents the total precipitation (rainfall and snowfall). The total is partitioned between snowfall and rainfall using :nml:mem:`JULES_DRIVE::t_for_snow`, and rainfall is then further partitioned into large-scale and convective components using :nml:mem:`JULES_DRIVE::t_for_con_rain`. Convective snowfall is assumed to be zero. + +``tot_rain`` and ``tot_snow`` + Two precipitation fields are input: total rainfall and total snowfall. The rainfall is partitioned between large-scale and convective, using :nml:mem:`JULES_DRIVE::t_for_con_rain`. Convective snowfall is assumed to be zero. + +``ls_rain``, ``con_rain`` and ``tot_snow`` + Three precipitation fields are input: large-scale rainfall, convective rainfall and total snowfall. This cannot be used with :nml:mem:`JULES_SURFACE::l_point_data` = TRUE. Convective snowfall is assumed to be zero. + +``ls_rain``, ``con_rain``, ``ls_snow`` and ``con_snow`` + Four precipitation fields are input: large-scale rainfall, convective rainfall, large-scale snowfall and convective snowfall. This cannot be used with :nml:mem:`JULES_SURFACE::l_point_data` = TRUE. Note that this is the only option that considers convective snowfall. + +If ``precip`` is given, the first method is used. If ``precip`` is *not* given but ``tot_rain`` is, the second method is used. If *neither* ``precip`` *nor* ``tot_rain`` are given but ``tot_snow`` is, the third method is used. The fourth method is used in all other cases. + +The concept of convective and large-scale (or dynamical) components of precipitation comes from atmospheric models, in which the precipitation from small-scale (convective) and large-scale motions is often calculated separately. If JULES is to be driven by the output from such a model, the driving data might include these components. + +.. warning:: If :nml:mem:`l_daily_disagg` = TRUE, then :nml:mem:`interp` for each precipitation variable should be ``f`` or ``nf``. + ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Description | ++============================+===========================================================================================================+ +| ``precip`` | Precipitation rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``tot_rain`` | Rainfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``tot_snow`` | Snowfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``ls_rain`` | Large-scale rainfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``con_rain`` | Convective rainfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``ls_snow`` | Large-scale snowfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``con_snow`` | Convective snowfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ + +Wind variables +^^^^^^^^^^^^^^ + +The wind variables can be given in one of two ways: + +``wind`` + The wind speed is input. + +``u`` and ``v`` + The two components of the horizontal wind (e.g. the southerly and westerly components) are input. + +If ``wind`` is given, then the first method is used. The second method is used in all other cases. + ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Description | ++============================+===========================================================================================================+ +| ``wind`` | Total wind speed (m s\ :sup:`-1`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``u`` | Zonal component of the wind (m s\ :sup:`-1`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| ``v`` | Meridional component of the wind (m s\ :sup:`-1`). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ + + +Daily disaggregator variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If :nml:mem:`l_daily_disagg` = TRUE, then the diurnal temperature range is also required: + ++----------------------------+-----------------------------------------------------------------------------------------------------------+ +| Name | Description | ++============================+===========================================================================================================+ +| ``dt_range`` | Diurnal temperature range (K). | ++----------------------------+-----------------------------------------------------------------------------------------------------------+ + + +Examples of specifying driving data +----------------------------------- + +The examples below illustrate the use of some of the key settings in the namelist; other settings are omitted for clarity. + +Single point ASCII driving data for one year +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + &JULES_DRIVE + + data_start = '1997-01-01 00:00:00', + data_end = '1998-01-01 00:00:00', + data_period = 1800, + + file = "met_data.dat", + + nvars = 8, + var = 'sw_down' 'lw_down' 'tot_rain' 'tot_snow' 't' 'wind' 'pstar' 'q', + interp = 'nf' 'nf' 'nf' 'nf' 'nf' 'nf' 'nf' 'nf', + + diff_frac_const = 0.1, + t_for_con_rain = 293.15 + / + +:nml:mem:`JULES_DRIVE::data_start`, :nml:mem:`JULES_DRIVE::data_end` and :nml:mem:`JULES_DRIVE::data_period` specify that the driving dataset provides one year (1997) of half-hourly data. + +:nml:mem:`JULES_DRIVE::read_list` is not given, so takes its default value of FALSE. This means that :nml:mem:`JULES_DRIVE::file` is used as either the single data file or a file name template. In this case there is no templating, so JULES treats the given file as the single data file for all data times. + +``sw_down`` and ``lw_down`` are given, so the first radiation scheme (above) is used. + +``precip`` is not given but ``tot_rain`` is, so the second precipitation scheme (above) is used. :nml:mem:`JULES_DRIVE::t_for_con_rain` = 293.15K means that rainfall is treated as convective in nature for temperatures at or above that threshold (not used if :nml:mem:`JULES_SURFACE::l_point_data` = TRUE). + +``wind`` is given, so total wind speed is used (first scheme above). + +``diff_rad`` is not given, so the diffuse radiation is calculated as 0.1 (the value of :nml:mem:`JULES_DRIVE::diff_frac_const`) times the total shortwave radiation. + +The driving data file (``met_data.dat``) should look similar to:: + + # solar long rain snow temp wind press humid + 3.3 187.8 0.0 0.0 259.10 3.610 102400.5 1.351E-03 + 89.5 185.8 0.0 0.0 259.45 3.140 102401.9 1.357E-03 + 142.3 186.4 0.0 0.0 259.85 2.890 102401.0 1.369E-03 + # ----- data for later times ---- + + +Driving data from NetCDF files with one variable per file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + &JULES_DRIVE + + data_start = '1982-07-01 03:00:00', + data_end = '1996-01-01 00:00:00', + data_period = 10800, + + read_list = T, + nfiles = 162, + + file = "./file_list.txt", + + nvars = 8, + var = 'sw_down' 'lw_down' 'tot_rain' 'tot_snow' 't' 'wind' 'pstar' 'q', + var_name = 'SWdown' 'LWdown' 'Rainf' 'Snowf' 'Tair' 'Wind' 'PSurf' 'Qair', + tpl_name = 'SWdown' 'LWdown' 'Rainf' 'Snowf' 'Tair' 'Wind' 'PSurf' 'Qair', + interp = 'nb' 'nb' 'nb' 'nb' 'i' 'i' 'i' 'i', + + diff_frac_const = 0.1, + t_for_con_rain = 293.15 + / + +In this example, the driving dataset provides 13.5 years of driving data on a 3 hourly timestep. + +:nml:mem:`JULES_DRIVE::read_list` = TRUE indicates that the names and start times of the data files should be read from ``file_list.txt``. The first few lines of this file are:: + + 'met_data/%vv_data/%vv198207.nc', '1982-07-01 03:00:00' + 'met_data/%vv_data/%vv198208.nc', '1982-08-01 03:00:00' + 'met_data/%vv_data/%vv198209.nc', '1982-09-01 03:00:00' + # ------ rest of file not shown ----- + +The presence of the variable name templating string in each file name shows that we are using :doc:`variable name templating `. The dates show that we do in fact have monthly files, but we cannot use time templating for these files because the start time of 03H does not conform to the requirements. + +Furthermore, files for each variable are stored in separate directories. The values from :nml:mem:`JULES_DRIVE::tpl_name` will be substituted into the file name templates in place of the substitution string (``%vv``). For example, pressure is held in files with names like ``met_data/PSurf_data/PSurf198207.nc``, and temperature in files like ``met_data/Tair_data/Tair198207.nc``. + +The driving variable setup is as the previous example. + + diff --git a/doc/source/namelists/fire.nml.rst b/doc/source/namelists/fire.nml.rst new file mode 100644 index 00000000..899f7c4d --- /dev/null +++ b/doc/source/namelists/fire.nml.rst @@ -0,0 +1,60 @@ +``fire.nml`` +=================== + +This file contains a single namelist called :nml:lst:`FIRE_SWITCHES` that sets time-invariant parameters for performing wildfire-related calculations. + +``FIRE_SWITCHES`` namelist members +----------------------------------- + +.. nml:namelist:: FIRE_SWITCHES + +.. nml:member:: l_fire + + :type: logical + :default: F + + Switch to enable the fire module. + + TRUE + The fire module will be executed according to the settings of subsequent namelist members. + + FALSE + The fire module will not be executed and subsequent members of the namelist will have no effect. + + + +.. nml:member:: mcarthur_flag + + :type: boolean + :default: F + + Switch for calculating the McArthur Forest Fire Danger Index (FFDI). + + +.. nml:member:: mcarthur_opt + + :type: real + :default: MDI + + Switch for choosing which method of calculating the soil moisture deficit required for the McArthur Forest Fire Danger Index (FFDI). 1 uses the model soil moisture, 2 uses a fixed value of 120 mm. + +.. nml:member:: canadian_flag + + :type: boolean + :default: F + + Switch for calculating the Canadian Fire Weather Index (FWI). + +.. nml:member:: canadian_hemi_opt + + :type: boolean + :default: F + + If TRUE, then the month-dependent parameters used in the calculation will be offset by 6 months for the southern hemisphere. This will cause a discontinuity in results when crossing the equator. + +.. nml:member:: nesterov_flag + + :type: boolean + :default: F + + Switch for calculating the Nesterov Index. diff --git a/doc/source/namelists/imogen.nml.rst b/doc/source/namelists/imogen.nml.rst new file mode 100644 index 00000000..8090bd12 --- /dev/null +++ b/doc/source/namelists/imogen.nml.rst @@ -0,0 +1,423 @@ +``imogen.nml`` +============== + + +This file contains three namelists called :nml:lst:`IMOGEN_ONOFF_SWITCH`, :nml:lst:`IMOGEN_RUN_LIST` and :nml:lst:`IMOGEN_ANLG_VALS_LIST`. Values from this section are only used if IMOGEN is enabled. This is done via the following switch: :nml:mem:`IMOGEN_ONOFF_SWITCH::l_imogen` = TRUE. + +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 files to derive the driving data. The driving data is derived from: 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`. + +IMOGEN can either take a daily or a monthly climatology to drive JULES. This is controlled by :nml:mem:`IMOGEN_ONOFF_SWITCH::l_daily_metdata_climatol`. If the driving data changes during runtime (:nml:mem:`IMOGEN_RUN_LIST::l_change_metdata` = TRUE) there are different methods for changing it (:nml:mem:`IMOGEN_RUN_LIST::change_metdata_method`). + +If :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` = 2, then use anomalies from the given climatology. Otherwise (:nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` set to 1 or 3) use pattern-scaling (spatial patterns of changes in each meteorological driving variable per degree of global temperature change). Patterns can be derived at the required spatial resolution using ESMValTool . + +If :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` = 3, then IMOGEN reads the global mean temperature change via the :nml:lst:`JULES_PRESCRIBED`. IMOGEN still reads the other 1d data from ascii files - this will change in the near future. + +.. seealso:: + References: + + * Huntingford, C. and P. M. Cox (2000), + An analogue model to derive additional climate change scenarios + from existing GCM simulations, Climate Dynamics 16(8): 575-586. + https://doi.org/10.1007/s003820000067 + * Huntingford, C., et al. (2010), + IMOGEN: an intermediate complexity model to evaluate terrestrial + impacts of a changing climate, + Geoscientific Model Development 3(2): 679-687. + https://doi.org/10.5194/gmd-3-679-2010 + * Comyn-Platt, E., et al. (2018), + Carbon budgets for 1.5 and 2 C targets lowered by natural + wetland and permafrost feedbacks, + Nature Geoscience 11(8): 568-573. + https://doi.org/10.1038/s41561-018-0174-9 + * Zelazowski, P., et al. (2018), + Climate pattern-scaling set for an ensemble of 22 + GCMs–adding uncertainty to the IMOGEN version 2.0 impact system, + Geoscientific Model Development 11.2: 541-560. + https://doi.org/10.5194/gmd-11-541-2018 + * Mathison, C., et al. (2024), + A rapid application emissions-to-impacts tool for scenario assessment: + Probabilistic Regional Impacts from Model patterns and Emissions (PRIME), + Geoscientific Model Development. + https://doi.org/10.5194/egusphere-2023-2932, 2024 + +``IMOGEN_ONOFF_SWITCH`` namelist members +---------------------------------------- + +.. nml:namelist:: IMOGEN_ONOFF_SWITCH + + +.. nml:member:: l_imogen + + :type: logical + :default: F + + Switch for IMOGEN. + + TRUE + IMOGEN is used to generate meteorological forcing data and drive JULES. + + FALSE + No effect. + + .. note:: + If IMOGEN is enabled, at most only :nml:mem:`JULES_DRIVE::z1_tq_vary`, :nml:mem:`JULES_DRIVE::z1_tq_in`, :nml:mem:`JULES_DRIVE::z1_uv_in`, :nml:mem:`JULES_DRIVE::z1_tq_file` and :nml:mem:`JULES_DRIVE::z1_tq_var_name` are used from the :nml:lst:`JULES_DRIVE` namelist. + + +.. nml:member:: l_daily_metdata_climatol + + :type: logical + :default: F + + If TRUE, then the driving climatology is supplied as daily data with a 360 day calendar otherwise the driving climatology is supplied as monthly data. + + + +``IMOGEN_RUN_LIST`` namelist members +------------------------------------ + +.. nml:namelist:: IMOGEN_RUN_LIST + + +.. nml:member:: co2_init_ppmv + + :type: real + :default: 286.085 + + Initial CO2 concentration (ppmv). + + +.. nml:member:: file_scen_emits + + :type: character + :default: None + + If used, file containing CO2 emissions. + + This file is expected to be in a specific format - see the IMOGEN example. + + +.. nml:member:: file_non_co2_radf + + :type: character + :default: None + + If used, file containing non-CO2 radiative forcing values. + + This file is expected to be in a specific format - see the IMOGEN example. + + +.. nml:member:: nyr_non_co2 + + :type: integer + :default: 21 + + Number of years for which non-co2 forcing is prescribed. + + +.. nml:member:: file_scen_co2_ppmv + + :type: character + :default: None + + If used, file containing CO2 concentration (ppmv). + + This file is expected to be in a specific format - see the IMOGEN example. + + +.. nml:member:: ch4_init_ppbv + + :type: real + :default: 774.1 + + Initial CH4 concentration (ppbv). + + Only if :nml:mem:`land_feed_ch4` = TRUE. + + +.. nml:member:: yr_fch4_ref + + :type: real + :default: 2000 + + Year for reference wetland CH4 emissions and atmospheric CH4 decay rate, i.e. :nml:mem:`fch4_ref`, :nml:mem:`tau_ch4_ref` & :nml:mem:`ch4_ppbv_ref`. + + Only if :nml:mem:`land_feed_ch4` = TRUE. + + +.. nml:member:: ch4_ppbv_ref + + :type: real + :default: 1751.02 + + Reference atmosphere CH4 concentration at :nml:mem:`yr_fch4_ref` (ppbv). + + Only if :nml:mem:`land_feed_ch4` = TRUE. + + +.. nml:member:: tau_ch4_ref + + :type: real + :default: 8.4 + + Lifetime of CH4 in atmosphere at :nml:mem:`yr_fch4_ref` (years). Value used in Gedney et al. (2004) S3 (Table 1) from TAR, Table 4.3 (subscript d). + + Only if :nml:mem:`land_feed_ch4` = TRUE. + + +.. nml:member:: fch4_ref + + :type: real + :default: 180.0 + + Reference wetland CH4 emissions for reference year :nml:mem:`yr_fch4_ref` (Tg CH4/yr). + + Only if :nml:mem:`land_feed_ch4` = TRUE. + + +.. nml:member:: file_ch4_n2o + + :type: character + :default: None + + File containing the CH4 and N2O atmos concs. The number of years in this file is defined by :nml:mem:`nyr_ch4_n2o`. This file is expected to be an ascii file with three columns: the first column is the year, the second column is the CH4 concentration (ppbv) and the third column is the N2O concentration (ppbv). There is one row for each year and no header. + + Only if :nml:mem:`land_feed_ch4` = TRUE. + + +.. nml:member:: nyr_ch4_n2o + + :type: integer + :default: 241 + + Number of years of CH4 and N2O data in :nml:mem:`file_ch4_n2o`. + + Only if :nml:mem:`land_feed_ch4` = TRUE. + + +.. nml:member:: l_change_metdata + + :type: logical + :default: T + + If TRUE, then the driving data is changed according to the value of :nml:mem:`change_metdata_method`. + + +.. nml:member:: change_metdata_method + + :type: integer + :permitted: 1,2 or 3 + :default: None + + Choice of method for allowing the driving data to change over time (used if :nml:mem:`l_change_metdata` = TRUE) + + Possible values are: + + 1. | IMOGEN provides jules forcing based on the analogue model and spatial patterns of sensitivity to global mean temperature change. + | This can including changing atmospheric CO2 (:nml:mem:`include_co2` = TRUE) and can be emissions driven (:nml:mem:`c_emissions` = True) or concentration driven (:nml:mem:`c_emissions` = False) + | Feedbacks can be included (:nml:mem:`land_feed_ch4`, :nml:mem:`land_feed_co2`, :nml:mem:`ocean_feed`) + | An additional non-CO2 rdiative forcing can also be prescribed (:nml:mem:`file_non_co2_radf`). + 2. | Time series of anomaly data provided + | Requires CO2 concentration data (:nml:mem:`include_co2` = TRUE and :nml:mem:`c_emissions` = False) + | Currently no feedbacks included + 3. | IMOGEN provides jules forcing based on the global mean temperature change and the climate patterns. + | Requires CO2 concentration data (:nml:mem:`include_co2` = TRUE and :nml:mem:`c_emissions` = False) + | Currently no feedbacks included + + + +.. nml:member:: c_emissions + + :type: logical + :default: T + + If TRUE, CO2 concentration is calculated. + + +.. nml:member:: include_co2 + + :type: logical + :default: T + + If TRUE, include adjustments to CO2 values. + + +.. nml:member:: include_non_co2_radf + + :type: logical + :default: T + + If TRUE, include adjustments to non-CO2 radiative forcing. + + + +.. nml:member:: land_feed_co2 + + :type: logical + :default: F + + If TRUE, include land CO2 feedbacks on atmospheric CO2. + + +.. nml:member:: land_feed_ch4 + + :type: logical + :default: F + + If TRUE, include wetland CH4 feedbacks on atmospheric CH4. Prescribed CH4 concentrations assume a non-varying natural wetland CH4 component. However, when :nml:mem:`land_feed_ch4` = TRUE the constant wetland CH4 emissions are perturbed using the anomaly in modelled natural wetland CH4 emission. The methane emissions are calculated for the diagnosed wetland area when :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE. These are accumulated and passed to IMOGEN. + + To ensure consistency with the observed atmospheric CH4 growth rate the model needs to be calibrated to produce :nml:mem:`fch4_ref` TgCh4 per year (default 180) for the year :nml:mem:`yr_fch4_ref` (default 2000). This is done by calibrating q10_ch4 (either :nml:mem:`JULES_SOIL_BIOGEOCHEM::q10_ch4_cs`, :nml:mem:`JULES_SOIL_BIOGEOCHEM::q10_ch4_npp`, :nml:mem:`JULES_SOIL_BIOGEOCHEM::q10_ch4_resps`, depending on whether cs, npp or resps is defined as the substrate by :nml:mem:`JULES_SOIL_BIOGEOCHEM::ch4_substrate`) and const_ch4 (either :nml:mem:`JULES_SOIL_BIOGEOCHEM::const_ch4_cs`, :nml:mem:`JULES_SOIL_BIOGEOCHEM::const_ch4_npp`, :nml:mem:`JULES_SOIL_BIOGEOCHEM::const_ch4_resps`, again depending on whether cs, npp or resps is defined as the substrate by :nml:mem:`JULES_SOIL_BIOGEOCHEM::ch4_substrate`). The calibration can be carried out as discussed in Comyn-Platt et al. (2018) and needs to be checked before proceeding because the model won't necessarily produce the correct values by default. + + For wetland CH4 feedbacks values for the following: :nml:mem:`fch4_ref`, :nml:mem:`tau_ch4_ref`, :nml:mem:`ch4_ppbv_ref`, :nml:mem:`yr_fch4_ref`, :nml:mem:`ch4_init_ppbv`, :nml:mem:`file_ch4_n2o`, and :nml:mem:`nyr_ch4_n2o` are also required. + + .. seealso:: + References: + + * Gedney, N., Cox, P. M. & Huntingford, C. Climate feedback from wetland methane emissions. Geophys. Res. Lett. 31, L20503 (2004). https://doi.org/10.1029/2004GL020919 + + * Comyn-Platt, E., et al. (2018), + Carbon budgets for 1.5 and 2 C targets lowered by natural + wetland and permafrost feedbacks, + Nature Geoscience 11(8): 568-573. + https://doi.org/10.1038/s41561-018-0174-9 + + +.. nml:member:: ocean_feed + + :type: logical + :default: F + + If TRUE, include ocean feedbacks on atmospheric CO2. + + +.. nml:member:: nyr_emiss + + :type: integer + :default: 241 + + Number of years of emission data in file. + + +.. nml:member:: initialise_from_dump + + :type: logical + :default: F + + Indicates how the IMOGEN prognostic variables will be initialised. + + TRUE + Use a dump file (specified in :nml:mem:`dump_file` below) from a previous run with IMOGEN to initialise the IMOGEN prognostics. + + FALSE + IMOGEN will handle the initialisation of its prognostics internally. + + +.. nml:member:: dump_file + + :type: character + :default: None + + The name of the dump file to initialise from. + + Only used if :nml:mem:`initialise_from_dump` = TRUE. + + + + +``IMOGEN_ANLG_VALS_LIST`` namelist members +------------------------------------------ + +.. nml:namelist:: IMOGEN_ANLG_VALS_LIST + + +.. nml:member:: diff_frac_const_imogen + + :type: real + :default: 0.4 + + IMOGEN uses this instead of :nml:mem:`JULES_DRIVE::diff_frac_const` + + +.. nml:member:: q2co2 + + :type: real + :default: 3.74 + + Radiative forcing due to doubling CO2 (W m\ :sup:`-2`). + + +.. nml:member:: f_ocean + + :type: real + :default: 0.711 + + Fractional coverage of the ocean. + + +.. nml:member:: kappa_o + + :type: real + :default: 383.8 + + Ocean eddy diffusivity (W m\ :sup:`-1` K\ :sup:`-1`). + + +.. nml:member:: lambda_l + + :type: real + :default: 0.52 + + Inverse of climate sensitivity over land (W m\ :sup:`-2` K\ :sup:`-1`). + + +.. nml:member:: lambda_o + + :type: real + :default: 1.75 + + Inverse of climate sensitivity over ocean (W m\ :sup:`-2` K\ :sup:`-1`). + + +.. nml:member:: mu + + :type: real + :default: 1.87 + + Ratio of land to ocean temperature anomalies. + + +.. nml:member:: t_ocean_init + + :type: real + :default: 289.28 + + Initial ocean temperature (K). + + +.. nml:member:: file_patt + + :type: character + :default: None + + Netcdf file containing the patterns. It should be monthly data (12 months total) with the dimension 'imogen_drive' representing time. + + +.. nml:member:: file_clim + + :type: character + :default: None + + Netcdf file containing initialising climatology. It should be monthly data (12 months total) with the dimension 'imogen_drive' representing time. + + +.. nml:member:: file_base_anom + + :type: character + :default: None + + 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/doc/source/namelists/initial_conditions.nml.rst b/doc/source/namelists/initial_conditions.nml.rst new file mode 100644 index 00000000..914e8f5c --- /dev/null +++ b/doc/source/namelists/initial_conditions.nml.rst @@ -0,0 +1,516 @@ +``initial_conditions.nml`` +========================== + + +This file contains a single namelist called :nml:lst:`JULES_INITIAL` that is used to set up the initial state of prognostic variables. + + +``JULES_INITIAL`` namelist members +---------------------------------- + +.. nml:namelist:: JULES_INITIAL + +The values of all prognostic variables must be set at the start of a run. This initial state, or initial condition, can be read from a "dump" from an earlier run of the model, or may be read from a different file. Another option is to prescribe a simple or idealised initial state by giving constant values for the prognostic variables directly in the namelist. It is also possible to set some fields using values from a file (e.g. a dump) but to set others to constants given in the namelist. + + +.. nml:member:: dump_file + + :type: logical + :default: F + + Indicates whether the given :nml:mem:`file` is a dump from a previous run of JULES. + + TRUE + The file is a JULES dump file. + + FALSE + The file is not a JULES dump file. + + +.. nml:member:: total_snow + + :type: logical + :default: F + + Switch controlling simplified initialisation of snow variables. + + TRUE + Only the total mass of snow on each surface tile (see ``snow_tile`` in :ref:`list-of-initial-condition-variables`) is required to be input, and all related variables will be calculated from this or simple assumptions made. All the snow is assumed to be on the ground (not in the canopy). + + FALSE + All snow variables required for the current configuration must be input separately (see :ref:`list-of-initial-condition-variables`). + + +.. nml:group:: Members used to set up spatially varying properties + + .. nml:member:: file + + :type: character + :default: None + + The file to read initial conditions from. + + If :nml:mem:`use_file` (see below) is FALSE for every variable, this will not be used. + + 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 `. + + + .. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of initial condition variables that will be provided. + + See :ref:`list-of-initial-condition-variables` for those required for a particular configuration. + + .. note:: If :nml:mem:`dump_file` = TRUE and :nml:mem:`nvars` = 0, then the model will attempt to initialise all required variables from the given dump file. + + + .. nml:member:: var + + :type: character(nvars) + :default: None + + List of initial condition variable names as recognised by JULES (see :ref:`list-of-initial-condition-variables`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + + + .. nml:member:: use_file + + :type: logical(nvars) + :default: T + + For each JULES variable specified in :nml:mem:`var`, this indicates if it should be read from the specified file or whether a constant value is to be used. + + TRUE + The variable will be read from the file. + + FALSE + The variable will be set to a constant value everywhere using :nml:mem:`const_val` below. + + + .. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = TRUE, this is the name of the variable in the file containing the data. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + This is not used for variables where :nml:mem:`use_file` = FALSE, but a placeholder must still be given in that case. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + + + .. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name in place of the variable name substitution string. + + If the file name does not use variable name templating, this is not used. + + + .. nml:member:: const_val + + :type: real(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = FALSE, this is a constant value that the variable will be set to at every point in every layer. + + This is not used for variables where :nml:mem:`use_file` = TRUE, but a placeholder must still be given. + + .. nml:member:: l_broadcast_soilt + + :type: logical + :default: False + + Switch to allow non-soil tiled initial condition data to be broadcast to all soil tiles. This is only used when :nml:mem:`JULES_SOIL::l_tile_soil` is enabled. This helps distribute the model state, for example from a non-soil tiled run into a new run with soil tiling. Spin up of the model state should be considered when using this option. + + Note that if :nml:mem:`JULES_SOIL::l_tile_soil` = TRUE and values on soil tiles are available to define the initial state (e.g. from a previous run with soil tiling), :nml:mem:`l_broadcast_soilt` should be set to FALSE. Setting it to TRUE will result in the run failing because it will attempt to read a non-tiled variable. + +.. _list-of-initial-condition-variables: + +List of initial condition variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All input to the model must be on the same grid (see :doc:`/input/overview`), and initial conditions are no different. Even when the variable is only required for land points, values must be provided for the full input grid. Variables read as initial conditions must have no time dimension. + +The variables it is possible to specify as initial conditions can be grouped into 'types' depending on the number and size of the levels dimensions they are required to have. For NetCDF files, the dimension names are those specified in the :nml:lst:`JULES_INPUT_GRID` namelist. For variables with no type specified, no levels dimensions should be used. + +The required levels dimensions for each initial condition 'type' are given in the following table: + +.. tabularcolumns:: |p{2.5cm}|p{2cm}|p{4cm}|p{6.5cm}| + ++---------+------------------+-----------------------------------------------+--------------------------------------------------------+ +| Type | Number of levels | Levels dimension name(s) | Levels dimension size(s) | +| | dimensions | | | ++=========+==================+===============================================+========================================================+ +| soil | 1 | :nml:mem:`JULES_INPUT_GRID::soil_dim_name` | :nml:mem:`JULES_SOIL::sm_levels` | ++---------+------------------+-----------------------------------------------+--------------------------------------------------------+ +| pft | 1 | :nml:mem:`JULES_INPUT_GRID::pft_dim_name` | :nml:mem:`JULES_SURFACE_TYPES::npft` | ++---------+------------------+-----------------------------------------------+--------------------------------------------------------+ +| cpft | 1 | :nml:mem:`JULES_INPUT_GRID::cpft_dim_name` | :nml:mem:`JULES_SURFACE_TYPES::ncpft` | ++---------+------------------+-----------------------------------------------+--------------------------------------------------------+ +| type | 1 | :nml:mem:`JULES_INPUT_GRID::type_dim_name` | ``ntype`` (:nml:mem:`JULES_SURFACE_TYPES::npft` + | +| | | | :nml:mem:`JULES_SURFACE_TYPES::nnvg`) | ++---------+------------------+-----------------------------------------------+--------------------------------------------------------+ +| surft | 1 | :nml:mem:`JULES_INPUT_GRID::tile_dim_name` | ``nsurft`` (1 if :nml:mem:`JULES_SURFACE::l_aggregate` | +| | | | = TRUE, ``ntype`` otherwise) | ++---------+------------------+-----------------------------------------------+--------------------------------------------------------+ +| sclayer | 1 | :nml:mem:`JULES_INPUT_GRID::sclayer_dim_name` | Number of soil biogeochemistry layers. | +| | | | | +| | | | If using the single-pool moodel | +| | | | (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 1 )| +| | | | this is 1. | +| | | | | +| | | | If using the 4-pool model | +| | | | (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2) | +| | | | with | +| | | | :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = FALSE | +| | | | this is 1, else with | +| | | | :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = TRUE | +| | | | this is equal to :nml:mem:`JULES_SOIL::sm_levels`. | +| | | | | +| | | | If using the ECOSSE model | +| | | | (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 3) | +| | | | this is equal to | +| | | | :nml:mem:`JULES_SOIL_ECOSSE::dim_cslayer`. | ++---------+------------------+-----------------------------------------------+--------------------------------------------------------+ +| scpool | 2 | :nml:mem:`JULES_INPUT_GRID::scpool_dim_name`, | number of soil carbon pools (1 if | +| | | :nml:mem:`JULES_INPUT_GRID::sclayer_dim_name` | :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 1, | +| | | | 4 otherwise) and number of soil biogeochemistry layers | +| | | | (see ``sclayer`` above) | ++---------+------------------+-----------------------------------------------+--------------------------------------------------------+ +| bedrock | 1 | :nml:mem:`JULES_INPUT_GRID::bedrock_dim_name` | :nml:mem:`JULES_SOIL::ns_deep` | +| | | | | +| | | | Only applicable if :nml:mem:`JULES_SOIL::l_bedrock` = | +| | | | TRUE | ++---------+------------------+-----------------------------------------------+--------------------------------------------------------+ +| snow | 2 | :nml:mem:`JULES_INPUT_GRID::tile_dim_name`, | ``nsurft`` (see above), :nml:mem:`JULES_SNOW::nsmax` | +| | | :nml:mem:`JULES_INPUT_GRID::snow_dim_name` | | +| | | | | +| | | | Only applicable if ``nsmax > 0`` | ++---------+------------------+-----------------------------------------------+--------------------------------------------------------+ + + +The required variables for a particular configuration, along with their 'type' as specified above, are given in the following table. + +.. tabularcolumns:: |p{3cm}|p{9cm}|p{3.5cm}| + ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Name | Description | Type | ++==================================+=========================================================================================+=========+ +| Always required | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``canopy`` | Amount of intercepted water that is held on each surface tile (kg m\ :sup:`-2`). | surft | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``cs`` | Soil carbon (kg m\ :sup:`-2`). | scpool | +| | | | +| | If using the single-pool model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 1), | | +| | this is the total soil carbon. | | +| | | | +| | Otherwise, this is the carbon in each of the 4 pools of the 4-pool or ECOSSE models. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``snow_tile`` | If :nml:mem:`JULES_VEGETATION::can_model` /= 4, this is the total snow on the surface | surft | +| | tile (since there is a single store which doesn't distinguish between snow on canopy | | +| | and under canopy). | | +| | | | +| | If :nml:mem:`JULES_VEGETATION::can_model` = 4 (and then only at surface tiles where | | +| | :nml:mem:`JULES_SNOW::cansnowpft` = TRUE), ``snow_tile`` is interpreted as the | | +| | snow on the canopy, except when overridden by :nml:mem:`JULES_INITIAL::total_snow` | | +| | = TRUE. | | +| | | | +| | If :nml:mem:`JULES_INITIAL::total_snow` = TRUE, ``snow_tile`` is used to hold the | | +| | total snow on the surface tile (and is subsequently put onto the ground at tiles that | | +| | distinguish between ground and canopy stores). | | +| | | | +| | Further details of snow initialisation are given below. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``t_soil`` | Temperature of each soil layer (K). | soil | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``tstar_tile`` | Temperature of each surface tile (K). This is the surface or skin temperature. | surft | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`JULES_VEGETATION::can_rad_mod` = 1 | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``gs`` | Surface conductance for water vapour (m s\ :sup:`-1`). | None | +| | | | +| | This is used to start the iterative calculation of gs for the first timestep only. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if ``sthuf`` is not prescribed for all levels in :nml:lst:`JULES_PRESCRIBED` | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``sthuf`` | Soil wetness for each soil layer. This is the mass of soil water (liquid and frozen), | soil | +| | expressed as a fraction of the water content at saturation. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`JULES_VEGETATION::l_phenol` = TRUE | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``lai`` | Leaf area index of each PFT. | pft | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`JULES_VEGETATION::l_triffid` = TRUE | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``canht`` | Height (m) of each PFT. | pft | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`JULES_VEGETATION::l_trif_biocrop` = TRUE | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``years_since_harvest`` | Number of years since the previous harvest. | pft | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`JULES_VEGETATION::l_veg_compete` = TRUE | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``frac`` | The fraction of land area of each gridbox that is covered by each surface type. | type | +| | N.B. values specified here will override those at :nml:lst:`JULES_FRAC` | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`JULES_IRRIG::l_irrig_dmd` = TRUE | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``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 | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``sthzw`` | Soil wetness in the deep LSH/TOPMODEL layer beneath the standard soil column. | None | +| | | | +| | This is the mass of soil water (liquid and frozen), expressed as a fraction of the | | +| | water content at saturation. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``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 | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``rgrain`` | Snow surface grain size (\ |mu|\ m) on each surface tile. | None | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`total_snow` = FALSE | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``rho_snow`` | Bulk density of lying snow (kg m\ :sup:`-3`). | surft | +| | | | +| | If :nml:mem:`JULES_INITIAL::total_snow` = TRUE then this is set as follows: | | +| | | | +| | * If :nml:mem:`JULES_SNOW::nsmax` = 0, it is set to | | +| | :nml:mem:`JULES_SNOW::rho_snow_const`. | | +| | * If :nml:mem:`JULES_SNOW::nsmax` > 0 and there is an existing snow pack, it is set to | | +| | :nml:mem:`JULES_SNOW::rho_snow_const`. | | +| | * If :nml:mem:`JULES_SNOW::nsmax` > 0 and there is no snow pack, it is set to | | +| | :nml:mem:`JULES_SNOW::rho_snow_fresh`. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``snow_depth`` | Depth of snow (kg m). | surft | +| | | | +| | If :nml:mem:`JULES_INITIAL::total_snow` = TRUE, this is calculated from mass and | | +| | density of snow. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`total_snow` = FALSE and :nml:mem:`JULES_VEGETATION::can_model` = 4 | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``snow_grnd`` | Amount of snow on the ground, beneath the canopy (kg m\ :sup:`-2`), on each surface | surft | +| | tile. | | +| | | | +| | If :nml:mem:`JULES_INITIAL::total_snow` = TRUE this is set to ``snow_tile`` at tiles | | +| | where :nml:mem:`JULES_VEGETATION::can_model` = 4 is active, and to zero at all other | | +| | tiles. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`total_snow` = FALSE and :nml:mem:`JULES_SNOW::nsmax` > 0 | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``nsnow`` | The number of snow layers on each surface tile. | surft | +| | | | +| | If :nml:mem:`JULES_INITIAL::total_snow` = TRUE this is calculated from the snow depth. | | +| | | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``snow_ds`` | Depth of snow in each layer (kg m). | snow | +| | | | +| | If :nml:mem:`JULES_INITIAL::total_snow` = TRUE this is calculated from the snow depth | | +| | and the number of snow layers. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``snow_ice`` | Mass of frozen water in each snow layer (kg m\ :sup:`-2`). | snow | +| | | | +| | If :nml:mem:`JULES_INITIAL::total_snow` = TRUE all snow is assumed to be ice. | | +| | | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``snow_liq`` | Mass of liquid water in each snow layer (kg m\ :sup:`-2`). | snow | +| | | | +| | If :nml:mem:`JULES_INITIAL::total_snow` = TRUE this is set to zero. | | +| | | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``tsnow`` | Temperature of each snow layer (K). | snow | +| | | | +| | If :nml:mem:`JULES_INITIAL::total_snow` = TRUE this is set to the temperature of the | | +| | top soil layer. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`total_snow` = FALSE, :nml:mem:`JULES_SNOW::nsmax` > 0 and :nml:mem:`JULES_RADIATION::l_snow_albedo` = TRUE | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``rgrainl`` | Snow grain size (\ |mu|\ m) on each surface tile in each snow layer. | snow | +| | | | +| | If :nml:mem:`JULES_INITIAL::total_snow` = TRUE this is set to ``rgrain``. | | +| | | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`JULES_VEGETATION::l_triffid` = TRUE and :nml:mem:`JULES_VEGETATION::l_landuse` = TRUE | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``frac_agr_prev`` | Gridbox agricultural/crop fraction from previous TRIFFID timestep. | none | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``wood_prod_fast`` | Carbon content of the wood products pool with a fast decay rate. | none | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``wood_prod_med`` | Carbon content of the wood products pool with a medium decay rate. | none | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``wood_prod_slow`` | Carbon content of the wood products pool with a slow decay rate. | none | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`JULES_VEGETATION::l_triffid` = TRUE and :nml:mem:`JULES_VEGETATION::l_landuse` = TRUE and | +| :nml:mem:`JULES_VEGETATION::l_trif_crop` = TRUE | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``frac_past_prev`` | Gridbox pasture fraction from previous TRIFFID timestep. | none | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`JULES_VEGETATION::l_triffid` = TRUE and :nml:mem:`JULES_VEGETATION::l_landuse` = TRUE and | +| :nml:mem:`JULES_VEGETATION::l_trif_biocrop` = TRUE | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``frac_biocrop_prev`` | Gridbox bioenergy fraction from previous TRIFFID timestep. | none | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if using 4-pool model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2) with | | +| :nml:mem:`JULES_VEGETATION::l_nitrogen` = TRUE., or if using ECOSSE | | +| (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 3) with :nml:mem:`JULES_SOIL_ECOSSE::l_soil_n` = TRUE. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``ns`` | Soil nitrogen (kg m\ :sup:`-2`). | scpool | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if using 4-pool model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2) and | | +| :nml:mem:`JULES_VEGETATION::l_nitrogen` = TRUE. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``n_inorg`` | Soil inorganic nitrogen (kg m\ :sup:`-2`). | sclayer | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if using ECOSSE (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 3) and | | +| :nml:mem:`JULES_SOIL_ECOSSE::l_soil_n` = TRUE. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``n_amm`` | Soil ammonium (kg m\ :sup:`-2`). | sclayer | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``n_nit`` | Soil nitrate (kg m\ :sup:`-2`). | sclayer | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE, :nml:mem:`JULES_RIVERS::i_river_vn` = '2' and | +| :nml:mem:`JULES_INITIAL::dump_file` = TRUE | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``rfm_surfstore_rp`` | Surface water storage on river routing points (m3) | none | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``rfm_substore_rp`` | Sub-surface water storage on river routing points (m3) | none | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``rfm_flowin_rp`` | Surface flow into a grid box on river routing points (m3) | none | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``rfm_bflowin_rp`` | Sub-surface flow into a grid box on river routing points (m3) | none | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| Required if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE, :nml:mem:`JULES_RIVERS::i_river_vn` = '1,3' and | +| :nml:mem:`JULES_INITIAL::dump_file` = TRUE | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| ``rivers_sto_rp`` | Water storage (kg) | none | +| | | | +| | **Alternatively**, can be initialised from an ancillary file via | | +| | :nml:lst:`JULES_RIVERS_PROPS`. It cannot be requested via :nml:lst:`JULES_INITIAL` | | +| | if it has already been initialised from an ancillary. | | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ +| 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 | ++----------------------------------+-----------------------------------------------------------------------------------------+---------+ + + +.. warning:: + 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:: + if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE, :nml:mem:`JULES_RIVERS::i_river_vn` = '1,3' and :nml:mem:`JULES_INITIAL::dump_file` = FALSE, + ``rivers_sto_rp`` is initialised to zero **unless** it is initialised from an ancillary via :nml:lst:`JULES_RIVERS_PROPS`. + +.. |mu| unicode:: μ .. u + + +Examples of specification of initial state +------------------------------------------ + +Specification of initial state at a single point +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This assumes that :nml:mem:`JULES_VEGETATION::l_phenol` = FALSE, :nml:mem:`JULES_VEGETATION::l_triffid` = FALSE, :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 1 and :nml:mem:`JULES_SNOW::nsmax` = 0. + +:: + + &JULES_INITIAL + file = "initial_conditions.dat", + + nvars = 8, + var = 'canopy' 'tstar_tile' 'cs' 'gs' 'rgrain' 'snow_tile' 'sthuf' 't_soil', + use_file = F F F F F F T T , + const_val = 0.0 276.78 12.1 0.0 50.0 0.0 + / + +Or using the alternative list syntax (see :doc:`intro`):: + + &JULES_INITIAL + file = "initial_conditions.dat", + + nvars = 8, + var(1) = 'canopy', use_file(1) = F, const_val(1) = 0.0 , + var(2) = 'tstar_tile', use_file(2) = F, const_val(2) = 276.78, + var(3) = 'cs', use_file(3) = F, const_val(3) = 12.1, + var(4) = 'gs', use_file(4) = F, const_val(4) = 0.0, + var(5) = 'rgrain', use_file(5) = F, const_val(5) = 50.0, + var(6) = 'snow_tile', use_file(6) = F, const_val(6) = 0.0, + var(7) = 'sthuf', use_file(7) = T, + var(8) = 't_soil', use_file(8) = T, + / + +This shows how a mixture of constant values and initial state from a file can be used. In this case, the first 6 variables will be set to constant values everywhere (:nml:mem:`JULES_INITIAL::use_file` = FALSE) with the last 2 read from the specified file (:nml:mem:`JULES_INITIAL::use_file` = TRUE). + +:nml:mem:`JULES_INITIAL::file` specifies an ASCII file to read the variables for which :nml:mem:`JULES_INITIAL::use_file` = TRUE from. + +Since the variables are arranged such that all those with :nml:mem:`JULES_INITIAL::use_file` = FALSE are first, we need only supply constant values for those variables that require them. + +The contents of ``initial_conditions.dat`` should look similar to:: + + # sthuf(1:4) t_soil(1:4) + 0.749 0.743 0.754 0.759 276.78 277.46 278.99 282.48 + +The data for each soil layer is given in consecutive columns. A comment line is used to indicate which columns comprise which variable (see :doc:`/input/overview` for more details). + +Specifying initial state for gridded data using NetCDF files is similar, except that: + +* :nml:mem:`JULES_INITIAL::var_name` is required for each variable read from file. +* If variable name templating is used, :nml:mem:`JULES_INITIAL::tpl_name` is required for each variable read from file. + + +Specification of initial state from an existing dump file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this example, we use an existing dump file (from a previous run) to set the initial values of all required variables. + +:: + + &JULES_INITIAL + dump_file = T, + file = "jules_dump.nc" + / + +:nml:mem:`JULES_INITIAL::dump_file` = TRUE indicates that the given file should be interpreted as a JULES dump file. + +:nml:mem:`JULES_INITIAL::file` specifies the dump file to read (in this case a NetCDF dump file). + +Since it is not specified, :nml:mem:`JULES_INITIAL::nvars` takes its default value of 0, which indicates that JULES should attempt to read all required variables from the given dump file. diff --git a/doc/source/namelists/intro.rst b/doc/source/namelists/intro.rst new file mode 100644 index 00000000..006813bd --- /dev/null +++ b/doc/source/namelists/intro.rst @@ -0,0 +1,35 @@ +Introduction to Fortran namelists +================================= + +Each namelist file read by JULES contains one or more Fortran namelists. Any content that does not form part of a namelist group is not read or interpreted in any way by Fortran, and so can be used as comments. + +A Fortran namelist combines several related variables (referred to as 'members' of the namelist) together, which are then read with a single statement. The members can appear in any order. A Fortran namelist takes the following format:: + + &GROUP_NAME + char_variable = "a char variable", + logical_variable = T, + nitems = 5, + list_variable = 0.1 0.2 0.3 0.4 0.5 + / + +The namelist definition is anything that appears between ``&GROUP_NAME`` and ``/``. Values are then declared for the namelist members using the form ``member_name = member_value``. The member names are determined by the definition of the namelist in the Fortran source code. The member names for the JULES namelists are documented in the following sections. + +Values for character variables must be enclosed in either single(' ') or double (" ") quotes. Logical values can be specified using ``.TRUE.``/``.FALSE.`` or with the shorthand ``T``/``F``. Integer and real values are specified simply by giving the value. The vast majority of compilers (all tested compilers) allow lists to be specified either horizontally or vertically, depending on preference. The following definitions are +identical:: + + list_variable = 0.1 0.2 0.3 0.4 0.5 + + list_variable(1) = 0.1 + list_variable(2) = 0.2 + list_variable(3) = 0.3 + list_variable(4) = 0.4 + list_variable(5) = 0.5 + +Namelists are an ideal input mechanism for programs like JULES that have a large number of inputs, most of which users never change from the default. Since each variable can have a sensible default value specified in the code, the user need only specify variables they wish to change from the default. This can substantially reduce the size and complexity of the namelist files. For example, suppose that in the above +example the namelist member ``logical_variable`` has a default value of ``.TRUE.``. Then the following namelist specification is equivalent to that above:: + + &GROUP_NAME + char_variable = "a char variable", + nitems = 5, + list_variable = 0.1 0.2 0.3 0.4 0.5 + / diff --git a/doc/source/namelists/jules_deposition.nml.rst b/doc/source/namelists/jules_deposition.nml.rst new file mode 100644 index 00000000..ed466c5b --- /dev/null +++ b/doc/source/namelists/jules_deposition.nml.rst @@ -0,0 +1,418 @@ +``jules_deposition.nml`` +============================= + + +This file contains options and parameters for modelling of dry deposition of atmospheric trace constituents. It contains a variable number of namelists depending on the required model configuration. The namelist :nml:lst:`JULES_DEPOSITION` is always required, the namelist :nml:lst:`JULES_DEPOSITION_SPECIES_SPECIFIC` and one or more instances of the namelist :nml:lst:`JULES_DEPOSITION_SPECIES` is required if dry deposition has been selected. + +.. warning:: + Atmospheric deposition in JULES is still in development. In this version, two options are provided: (1) :nml:mem:`JULES_DEPOSITION::dry_dep_model` = 1, which implements the existing UKCA interactive gas-phase dry deposition routines in JULES. The parameters are hard-wired in the code and only 4 surface tile configurations are permitted; and (2) :nml:mem:`JULES_DEPOSITION::dry_dep_model` = 2, which removes the surface tile restrictions and uses namelists to define the various deposition parameters. Deposition parameters specific to a single deposited species are input on :nml:lst:`JULES_DEPOSITION_SPECIES_SPECIFIC` namelist. There is a separate :nml:lst:`JULES_DEPOSITION_SPECIES` namelist for each deposited species for deposition parameters common to more than one deposited species. To activate the deposition code: set :nml:mem:`JULES_DEPOSITION::l_deposition` to TRUE. + + + +``JULES_DEPOSITION`` namelist members +------------------------------------- + +.. nml:namelist:: JULES_DEPOSITION + + +.. nml:member:: l_deposition + + :type: logical + :default: FALSE + + Switch to activate deposition code in JULES. + + TRUE + Model deposition in JULES. + + FALSE + Do not model deposition in JULES. + + .. note:: There is now a requirement to specify all surface types in :nml:lst:`JULES_SURFACE_TYPES` (the plant functional types need to be defined, e.g. :nml:mem:`JULES_SURFACE_TYPES::brd_leaf` =1, :nml:mem:`JULES_SURFACE_TYPES::ndl_leaf` =2, :nml:mem:`JULES_SURFACE_TYPES::c3_grass` =3, :nml:mem:`JULES_SURFACE_TYPES::c4_grass` =4, :nml:mem:`JULES_SURFACE_TYPES::shrub` =5 for the 5-pft configuration). + + +.. nml:group:: Only used if :nml:mem:`l_deposition` = TRUE. + + + .. nml:member:: dry_dep_model + + :type: integer + :permitted: 1, 2 + :default: none + + Choice for model of dry deposition. + + Possible values are: + + 1. | Parameterisation based on the interactive dry deposition scheme in the UKCA. + 2. | Parameterisation based on the interactive dry deposition scheme in the UKCA, with the restriction on the allowable surface tile configuration removed. + + + .. nml:member:: dep_h2_soil_scheme + + :type: integer + :permitted: 1, 2 + :default: none + + Choice for scheme for soil uptake of H2 from the atmosphere. + + Possible values are: + + 1. | Parameterisation based on Conrad & Seiler uptake scheme in the UKCA. + 2. | Parameterisation based on Paulot et al. scheme. + + Note: The Paulot et al. scheme is currently not available in UM-coupled JULES applications. + + + .. nml:member:: l_deposition_flux + + :type: logical + :default: FALSE + + Switch for calculation of deposition fluxes as opposed to deposition velocities. + + TRUE + Calculate deposition fluxes. This requires that the concentrations of atmopsheric tracer species are provided as prescribed data (see :ref:`supported-prescribed-variables`). + + FALSE + Calculate deposition velocities. + + + .. nml:member:: ndry_dep_species + + :type: integer + :permitted: >= 1 and <= 200 (ndep_species_max) + :default: none + + Number of species for which dry deposition is calculated. + + + .. nml:member:: tundra_s_limit + + :type: real + :default: none + + Latitude of southern limit of tundra (radians). This is used to alter the calculation of deposition of certain species in the tundra region (actually for all points north of this limit). Only used if the list of species (see :nml:mem:`JULES_DEPOSITION_SPECIES::dep_species_name_io`) includes one or more of 'CO', 'NO2', 'O3', 'PAN', 'PPAN', 'MPAN' or 'ONITU'. + + + .. nml:member:: dzl_const + + :type: real + :default: none + + Constant value for separation of boundary layer levels (m). All layer thicknesses are set to this value. This is used as a simple way to prescribe the layer thicknesses in standalone mode. This value can be overriden by prescribed data - see :nml:lst:`JULES_PRESCRIBED`. This can be considered as the representative depth for tracer concentration and the depth over which the deposition flux is removed. + + + .. nml:member:: l_deposition_from_ukca + + :type: logical + :default: FALSE + + Switch to determine calling routine for the JULES-based interactive deposition routines. + + TRUE + Calls the JULES-based deposition routines from the same UKCA routine ukca_chemistry_ctl (or the equivalents: ukca_chemistry_ctl_BE or ukca_chemistry_ctl_col), which is used to call the UKCA-based interactive deposition routines. + + FALSE + Calls the JULES-based deposition routines from the JULES routine surf_couple_extra. + + .. note:: For JULES standalone applications, the JULES-based deposition routines can only be called from surf_couple_extra() and :nml:mem:`JULES_DEPOSITION::l_deposition_from_ukca` is false and not enabled. For UM-coupled JULES applications, the JULES-based deposition routines can currently only be called from the UKCA and :nml:mem:`JULES_DEPOSITION::l_deposition_from_ukca` should be set to true. + + +.. nml:group:: (1) Switches that are only available for use in standalone JULES applications. + + .. nml:member:: l_deposition_gc_corr + + :type: logical + :default: FALSE + + Switch to use stomatal conductances with or without bare soil evaporation. + + TRUE + Use calculation of stomatal conductance without bare soil evaporation. + + FALSE + Use calculation of stomatal conductance with bare soil evaporation. + + +.. nml:group:: (2) For UM-coupled JULES applications, the following switches are set during the run to be equivalent to the corresponding switches in the UKCA (which are set in the UM run_ukca namelist). + + .. nml:member:: l_ukca_ddep_lev1 + + :type: logical + :default: FALSE + + Switch from the UKCA controlling which atmospheric levels in the boundary layer are used for dry deposition. For UM-coupled JULES applications, the UKCA interactive dry deposition switch (l_ukca_intdd in the run_ukca namelist) needs to be true. + + TRUE + Deposition occurs only from the lowest level in the atmospheric boundary layer. + + FALSE + Deposition occurs from all levels within the atmospheric boundary layer. + + + .. nml:member:: l_ukca_emsdrvn_ch4 + + :type: logical + :default: FALSE + + Switch from the UKCA in which the UKCA chemistry scheme uses methane (CH\ :sub:`4`) emissions instead of prescribed CH\ :sub:`4` surface mole fractions. + + TRUE + UKCA chemistry scheme uses methane (CH\ :sub:`4`) emissions. + + FALSE + UKCA chemistry scheme uses prescribed CH\ :sub:`4` surface mole fractions. + + +.. nml:group:: (3) Switches that are only available for UM-coupled JULES applications. The following switches are set during the run to be equivalent to the corresponding switches in the UKCA (which are set in the UM run_ukca namelist). + + .. nml:member:: l_ukca_ddepo3_ocean + + :type: logical + :default: FALSE + + Switch from the UKCA to use a mechanistic calculation for deposition of ozone to the ocean from Luhar et al. (2018). + + TRUE + Use the mechanistic calculation of Luhar et al. (2018). + + FALSE + Use the surface resistance term for water provided in rsurf_std_io. + + + .. nml:member:: l_ukca_dry_dep_so2wet + + :type: logical + :default: FALSE + + Switch from the UKCA to account for surface wetness in the dry deposition for SO\ :sub:`2`. The calculation uses the parameterisation in Erisman, Pul and Wyers (1994). + + TRUE + Account for surface wetness in the dry deposition for SO\ :sub:`2`. + + FALSE + Do not account for surface wetness in the dry deposition for SO\ :sub:`2`. + + +Notes on the ``JULES_DEPOSITION`` namelist +------------------------------------------ + +The height of the atmospheric boundary layer is required and is set to a default constant value of 1000 m. This value can be overridden via the namelist variable :nml:mem:`JULES_DRIVE::bl_height`, or can be prescribed (i.e. allowed to vary in time and/or space) by providing ``bl_height`` as prescribed data (see :ref:`supported-prescribed-variables`). + +The number of model levels in the boundary layer is required and is set to a default balues of 1. This can be overridden via the namelist variable :nml:mem:`JULES_NLSIZES::bl_levels`. The number of levels is only used to communicate with the atmospheric model (e.g. UKCA). + +The separation of the model levels in the boundary layer is required and is set to a constant value via :nml:mem:`dzl_const`. The separation can be prescribed (i.e. allowed to vary in time and/or space) by providing ``level_separation`` as prescribed data (see :ref:`supported-prescribed-variables`). This can be considered as the representative depth for tracer concentration and the depth over which the deposition flux is removed. + +If deposition fluxes (rather than deposition velocities) are to be calculated (see :nml:mem:`l_deposition_flux`), the concentrations of atmospheric tracer species need to be prescribed (see ``tracer_field`` in :ref:`supported-prescribed-variables`). + + +``JULES_DEPOSITION_SPECIES`` namelist members +--------------------------------------------- + +.. nml:namelist:: JULES_DEPOSITION_SPECIES + +This namelist should occur :nml:mem:`JULES_DEPOSITION::ndry_dep_species` times, with each occurence containing parameters for an atmospheric tracer species that is to be considered in dry deposition. + +.. nml:member:: dep_species_name_io + + :type: character + :default: none + + Name of an atmospheric tracer species to be included in deposition modelling. + + +.. nml:member:: dep_species_rmm_io + + :type: real + :default: none + + Relative molecular mass (g mol\ :sup:`-1`), as used in the UKCA. It is used in the calculation of the quasi-laminar resistance term (R\ :sub:`b`), if no diffusion coefficient is provided. + + +.. nml:member:: diffusion_coeff_io + + :type: real + :default: none + + Diffusion coefficient (m\ :sup:`-2` s\ :sup:`-1`). + + .. note:: If there is no measured value of the diffusion coefficient for any chemical species in the chemical mechanism, the diffusion coefficient for those species should be set to -1.0. This will be used to indicate that the diffusion coefficient will be calculated from the diffusion coefficient of water and the relative molecular masses of water and the chemical species. + + +.. nml:member:: rsurf_std_io + + :type: real(ntype) + :default: none + + Standard value of surface resistance for each surface type (s m\ :sup:`-1`). + + +.. nml:group:: Only used if :nml:mem:`dep_species_name_io` = ``NO2``, ``O3``, ``PAN``, ``PPAN``, ``MPAN`` or ``ONITU``. Values provided for other species will be ignored. + + .. nml:member:: diffusion_corr_io + + :type: real + :default: none + + Diffusion correction factor for stomatal resistance, accounting for the different diffusivities of water and other species (dimensionless). + + +.. nml:group:: Only used if :nml:mem:`dep_species_name_io` = ``CO``, ``NO2``, ``O3``, ``PAN``, ``PPAN``, ``MPAN`` or ``ONITU``. Values provided for other species will be ignored. + + .. nml:member:: r_tundra_io + + :type: real + :default: none + + Surface resistance used in tundra region (s m\ :sup:`-1`). + + +.. nml:group:: Only used if :nml:mem:`dep_species_name_io` = ``HNO3``, ``HONO2``, ``ISON`` and if :nml:mem:`JULES_TEMP_FIXES::l_fix_improve_drydep` = true, also for ``HCl``, ``HOCl``, ``HBr`` or ``HOBr``. + + .. nml:member:: dd_ice_coeff_io + + :type: real(3) + :default: none + + Coefficients in quadratic function relating dry deposition over ice to temperature. + + +``JULES_DEPOSITION_SPECIES_SPECIFIC`` namelist members +------------------------------------------------------ + +.. nml:namelist:: JULES_DEPOSITION_SPECIES_SPECIFIC + +This namelist is used for deposition parameters specific to a single deposited species. This namelist is used to avoid redundant entries on the :nml:lst:`JULES_DEPOSITION_SPECIES` namelists. + +.. nml:group:: Deposition parameters specific to :nml:mem:`JULES_DEPOSITION_SPECIES::dep_species_name_io` = ``CH4``. + + .. nml:member:: ch4_scaling_io + + :type: real + :default: none + + Scaling applied to methane soil uptake (dimensionless). (Originally this was used to match the value from the IPCC Third Assessment Report.) + + + .. nml:member:: ch4_mml_io + + :type: real + :default: none + + Factor used in UKCA to convert the methane soil uptake flux in (\ |mu|\ g m\ :sup:`-2` h\ :sup:`-1`) to a dry dep velocity (in m s\ :sup:`-1`). The current value of ch4_mml_io = 3600.0 * 0.016 * 1.0 x 10\ :sup:`9` * 1.75 x 10\ :sup:`-6` = 1.008 x 10\ :sup:`5`, where 0.016 is the relative molecular mass of methane (kg), 1.0 x 10\ :sup:`9` converts \ |mu|\ g to kg, and 1.75 x 10\ :sup:`-6` ppmv is the assumed mean global atmospheric volume mixing ratio of methane. + + + .. nml:member:: ch4dd_tundra_io + + :type: real(4) + :default: none + + Coefficients of cubic polynomial relating methane loss for tundra to temperature. Flux is in units of \ |mu|\ g (CH\ :sub:`4`) m\ :sup:`-2` s\ :sup:`-1`. + + + .. nml:member:: ch4_up_flux_io + + :type: real(ntype) + :default: none + + Value of uptake flux for methane for each surface type (\ |mu|\ g (CH\ :sub:`4`) m\ :sup:`-2` s\ :sup:`-1`). + + +.. nml:group:: Deposition parameters specific to :nml:mem:`JULES_DEPOSITION_SPECIES::dep_species_name_io` = ``H2``. + + + .. nml:member:: h2dd_c_io + + :type: real(ntype) + :default: none + + Constant in quadratic function relating hydrogen deposition to soil moisture (s m\ :sup:`-1`). + + + .. nml:member:: h2dd_m_io + + :type: real(ntype) + :default: none + + Coefficient of first order term in quadratic function relating hydrogen deposition to soil moisture (s m\ :sup:`-1`). + + + .. nml:member:: h2dd_q_io + + :type: real(ntype) + :default: none + + Coefficient of second order term in quadratic function relating hydrogen deposition to soil moisture (s m\ :sup:`-1`). + + +.. nml:group:: Deposition parameters specific to :nml:mem:`JULES_DEPOSITION_SPECIES::dep_species_name_io` = ``O3``. + + + .. nml:member:: cuticle_o3_io + + :type: real + :default: none + + Constant for calculation of cuticular resistance for ozone (s m\ :sup:`-1`). + + + .. nml:member:: r_wet_soil_o3_io + + :type: real + :default: none + + Wet soil surface resistance for ozone (s m\ :sup:`-1`). + + +Example +~~~~~~~ + +The following gives an example of how you would set up the :nml:lst:`JULES_DEPOSITION` namelist for atmospheric deposition for a JULES standalone run. + +.. code-block:: + + &JULES_DEPOSITION + dep_h2_soil_scheme=1 + dry_dep_model=2 + dzl_const=50.0 + l_deposition=.true. + l_deposition_flux=.false. + l_deposition_from_ukca=.false. + l_deposition_gc_corr=.false. + l_ukca_ddep_lev1=.false. + !!l_ukca_ddepo3_ocean=.false. + !!l_ukca_dry_dep_so2wet=.false. + l_ukca_emsdrvn_ch4=.false. + ndry_dep_species=1 + tundra_s_limit=0.866 + / + +Note: :nml:mem:`JULES_DEPOSITION::l_deposition_from_ukca` should be false for JULES standalone and true for UM-coupled JULES. :nml:mem:`JULES_DEPOSITION::l_ukca_ddepo3_ocean` and :nml:mem:`JULES_DEPOSITION::l_ukca_dry_dep_so2wet` are not available for JULES standalone applications. + +The following gives an example of how to set-up the :nml:lst:`JULES_DEPOSITION_SPECIES` and :nml:lst:`JULES_DEPOSITION_SPECIES_SPECIFIC` for the standard 5 pft/9 tile configuration for a single chemical species 'O3'. In general, ndry_dep_species will be greater than 1 and there will be :nml:lst:`JULES_DEPOSITION_SPECIES` namelists, one for each atmospheric species that is deposited. Some deposition parameters are required for all chemical species, others are species specific and not available (e.g. dd_ice_coeff_io for ``O3``). + +.. code-block:: + + &JULES_DEPOSITION_SPECIES + dep_species_name_io='O3' + dep_species_rmm_io=48.0 + diffusion_coeff_io=1.400000e-05 + diffusion_corr_io=1.6 + r_tundra_io=800.0 + rsurf_std_io=200.0,200.0,200.0,200.0,400.0,800.0,2200.0,800.0,2500.0 + / + + &JULES_DEPOSITION_SPECIES_SPECIFIC + ch4_mml_io=1.008e5 + ch4_scaling_io=15.0 + ch4_up_flux_io=39.5,50.0,30.0,37.0,27.5,0.0,0.0,27.5,0.0 + ch4dd_tundra_io=-4.757e-6,4.0288e-3,-1.13592,106.636 + cuticle_o3_io=5000.0 + h2dd_c_io=0.00197,0.00197,0.00177,1.2346,0.0001,0.0,0.0,0.0,0.0 + h2dd_m_io=-0.00419,-0.00419,-0.00414,-0.472,5*0.0 + h2dd_q_io=0.0,0.0,0.0,0.27,5*0.0 + r_wet_soil_o3_io=500.0 + / + +.. |mu| unicode:: μ .. u diff --git a/doc/source/namelists/jules_hydrology.nml.rst b/doc/source/namelists/jules_hydrology.nml.rst new file mode 100644 index 00000000..eed5d792 --- /dev/null +++ b/doc/source/namelists/jules_hydrology.nml.rst @@ -0,0 +1,217 @@ +``jules_hydrology.nml`` +======================= + + +This file sets the hydrology options. It contains one namelist called :nml:lst:`JULES_HYDROLOGY`. + + + +``JULES_HYDROLOGY`` namelist members +------------------------------------- + +.. nml:namelist:: JULES_HYDROLOGY + + +.. nml:member:: l_hydrology + + :type: logical + :default: F + + Switch to enable soil hydrology. + + TRUE + Use the JULES hydrology scheme to represent surface runoff, groundwater infiltration and soil evolution. + + FALSE + No hydrology scheme. + + +.. nml:member:: l_var_rainfrac + + :type: logical + :default: F + + Switch to enable variable large scale and convective rain fractions. This is intended for use with COUPLED MODELS ONLY. + + TRUE + In coupled models, the large-scale and convective rain fractions calculated by the atmosphere are used in throughfall and runoff calculations. + + In standalone, this is equivalent to **FALSE** with **0.5** for large-scale and :nml:mem:`JULES_SOIL::confrac` for convective rain as the functionality to supply the large-scale and convective rain fractions via the driving data does not exist. + + FALSE + These are assumed to be **1.0** for large-scale and :nml:mem:`JULES_SOIL::confrac` for convective rain. + + +.. nml:member:: l_top + + :type: logical + :default: F + + Switch for a TOPMODEL-type model of runoff production. + + TRUE + Use a TOPMODEL-type scheme. This is based on Gedney and Cox (2003); see also Clark and Gedney (2008). + + FALSE + No TOPMODEL scheme. + + .. seealso:: + References: + + * Gedney, N. and P.M.Cox, 2003 , The sensitivity of global climate model simulations to the representation of soil moisture heterogeneity, J. Hydrometeorology, 4, 1265-1275. + * Clark and Gedney, 2008, Representing the effects of subgrid variability of soil moisture on runoff generation in a land surface model, Journal of Geophysical Research - Atmospheres, 113, D10111, doi:10.1029/2007JD008940. + + +.. nml:member:: l_pdm + + :type: logical + :default: F + + Switch for a PDM-type model of runoff production. + + PDM is the Probability Distributed Model (Moore, 1985), implemented in JULES following Clark and Gedney (2008). + + TRUE + Use a PDM scheme. + + FALSE + No PDM scheme. + + .. seealso:: + References: + + * Moore, R. J. (1985), The probability-distributed principle and runoff production at point and basin scales, Hydrol. Sci. J., 30, 273-297. + * Clark and Gedney, 2008, Representing the effects of subgrid variability of soil moisture on runoff generation in a land surface model, Journal of Geophysical Research - Atmospheres, 113, D10111, doi:10.1029/2007JD008940. + + + .. note:: + Setting :nml:mem:`JULES_HYDROLOGY::l_top` = FALSE and :nml:mem:`JULES_HYDROLOGY::l_pdm` = FALSE selects a more basic runoff production scheme. In this scheme, surface runoff comes only from infiltration excess runoff (no saturation excess runoff), and subsurface runoff comes only from free drainage from the deepest soil layer (no lateral flow from mid-layers), as described in Essery et al. (2001, HCTN 30). + +.. nml:member:: l_limit_gsoil + + :type: logical + :default: F + + TRUE + Limit the soil conductance to the value when the top layer soil moisture is at the critical soil moisture. Below this threshold, the soil conductance follows Best et al. (2011) equation 7. + + FALSE + Allow the soil conductance to increase as the top layer soil moisture goes above the critical soil moisture, as in Best et al. (2011) equation 7. + + +.. nml:group:: Only used if :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE + + .. nml:member:: zw_max + + :type: real + :default: None + + The maximum allowed depth to the water table (m). + + This is the depth from the soil surface to the bottom of an additional layer that is used to track water tables below the standard soil model (which has layer thicknesses given by :nml:mem:`JULES_SOIL::dzsoil_io`). A value of ~10m can often be used (though the previous default value was 6m) - the suitability of any value depends on values of the ancillary variable ``fexp`` (see :ref:`list-of-topmodel-params`) and the sum of the soil layer thicknesses (denoted `sum_dzsoil` here). The saturated hydraulic conductivity declines exponentially with depth in the additional deep TOPMODEL layer, with decay parameter ``fexp``, and should be sufficiently small at depth ``zw_max`` that the flow at this depth can be neglected, that is `EXP(-fexp(zw_max-sum_dzsoil))` should be sufficiently small at all locations. (As a minimum guide, the code tests that the value of this expression is <= 0.05 and a warning is printed where this condition is not met; users should check model output logs for these messages.) + + + .. nml:member:: ti_max + + :type: real + :default: None + + The maximum possible value of the topographic index. A value of 10.0 can be used. + + .. nml:member:: ti_wetl + + :type: real + :default: None + + A calibration parameter used in the calculation of the wetland fraction. + + It is used to increment the "critical" value of the topographic index that is used to calculate the saturated fraction of the gridbox. It excludes locations with large values of the topographic index from the wetland fraction. A value of 1.5 can be used. + + + .. note:: + When TOPMODEL is on (i.e. :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE), JULES follows Gedney & Cox (2003, J Hydromet, eqn 14) in assuming that wetlands occur where gridcell elevation is low enough (assumed to be where topographic index is large enough) that the water table is above the land surface (topidx > :nml:mem:`ti_wetl`) but not above the land surface by enough that streamflow may be assumed to occur (topidx < :nml:mem:`ti_max`). Both :nml:mem:`ti_wetl` and :nml:mem:`ti_max` are levels calibrated from observed wetland fractions. So, if the water table is above the surface then JULES can calculate an areal fraction of total inundation (fsat) and also the areal fraction that is inundated but shallow enough to be stagnant/non-flowing (fwetl, with fwetl<=fsat), which is the 'wetland fraction'. + + + .. nml:member:: nfita + + :type: integer + :default: None + + The number of values tried when fitting wetland and saturation fractions to water table depth in the initialisation. A value of 20 can be used. + + This controls the range of ``cfit`` values tried in + ``calc_fit_fsat.F90`` where ``cfitmax = 0.15 * nfita`` + + + .. nml:member:: l_wetland_unfrozen + + :type: logical + :default: F + + TRUE + Treat the calculations of wetland and surface saturation fractions more like those of an unfrozen soil. + + FALSE + Use standard wetland and surface saturation fraction calculations. + + +.. nml:group:: Only used if :nml:mem:`JULES_HYDROLOGY::l_pdm` = TRUE + + .. nml:member:: dz_pdm + + :type: real + :default: None + + The depth of soil considered by PDM (m). + + A value of ~1m can be used. + + + .. nml:member:: b_pdm + + :type: real + :default: None + + PDM shape parameter (exponent) of the Pareto distribution controlling spatial variability of storage capacity. A value ~1 can be used. b=0 implies a constant storage capacity at all points. + + .. nml:member:: l_spdmvar + + :type: logical + :default: F + + TRUE + Use a linear function of topographic slope to calculate S0/Smax (the minimum soil water storage below which there is no saturation excess runoff from PDM, expressed as a fraction of the maximum storage Smax): S0/Smax=MAX(0.0,1-(slope/:nml:mem:`JULES_HYDROLOGY::slope_pdm_max`)). The slope is read as an ancillary field (see :nml:lst:`JULES_PDM`). + + This function will result in high S0/Smax values for flatter regions and low values for steeper regions, and has been tested for catchments in Great Britain. + + FALSE + Use a fixed value for S0/Smax, specified in :nml:mem:`JULES_HYDROLOGY::s_pdm`. + + + .. nml:group:: Only used if :nml:mem:`l_spdmvar` = TRUE + + .. nml:member:: slope_pdm_max + + :type: real + :default: None + + The maximum topographic slope (deg) in the linear function of slope to calculate S0/Smax. Slopes above this value will result in a S0/Smax value of zero. + + A value of 6.0 has been tested for slope fields calculated from a high resolution DEM dataset (50m IHDTM for Great Britain). + + For slopes calculated from coarser DEM datasets, a lower value might be more appropriate as fine-resolution features of the terrain are not included. + + + .. nml:group:: Only used if :nml:mem:`l_spdmvar` = FALSE + + .. nml:member:: s_pdm + + :type: real + :permitted: 0-1 + :default: None + + Minimum soil water storage below which there is no saturation excess runoff from PDM, expressed as a fraction of the maximum storage Smax) + + e.g. A value of 0 indicates that surface saturation can occur for any + value of water storage. A value of 0.5 would indicate that + no surface runoff is produced until the soil is 50% saturated. diff --git a/doc/source/namelists/jules_irrig.nml.rst b/doc/source/namelists/jules_irrig.nml.rst new file mode 100644 index 00000000..2f367f63 --- /dev/null +++ b/doc/source/namelists/jules_irrig.nml.rst @@ -0,0 +1,141 @@ +``jules_irrig.nml`` +======================== + + +This file sets the irrigation options. It contains one namelist called :nml:lst:`JULES_IRRIG`. + + +``JULES_IRRIG`` namelist members +-------------------------------- + +.. nml:namelist:: JULES_IRRIG + +This namelist specifies the different options available for setting up the irrigation. + +.. note:: + + Irrigation can be applied at a constant rate in three ways: + * 1. To apply a constant irrigation to all surface tiles the irrigation settings are as follows: frac_irrig_all_tiles=T, set_irrfrac_on_irrtiles=F and set a value for :nml:mem:`JULES_IRRIG_PROPS::const_frac_irr`. + * 2. To apply a constant irrigation to only specific surface tiles the irrigation settings are as follows: frac_irrig_all_tiles=F and set_irrfrac_on_irrtiles=T and set a value for :nml:mem:`JULES_IRRIG_PROPS::const_irrfrac_irrtiles`. + * 3. To apply a constant irrigation to specific surface tiles as an average across the gridbox, which is the way irrigation on specific tiles was done prior to vn5.7, the irrigation settings are as follows: frac_irrig_all_tiles=F, set_irrfrac_on_irrtiles=F and set a value for :nml:mem:`JULES_IRRIG_PROPS::const_frac_irr`. + + In both option 2 and 3, :nml:mem:`irrigtiles` is the index of surface tiles you wish to irrigate, the length of which is :nml:mem:`nirrtile` e.g. if you include wheat and maize in your run at index 5 and 6 then irrigtiles=5,6 and nirrtile=2. + +.. nml:member:: l_irrig_dmd + + :type: logical + :default: F + + Switch controlling the implementation of irrigation demand code. + + TRUE + Tiles are irrigated. + + FALSE + No effect. + + This must be set to TRUE if :nml:mem:`JULES_WATER_RESOURCES::l_water_irrigation` = TRUE. + + +.. nml:member:: l_irrig_limit + + :type: logical + :default: F + + Switch controlling whether the amount of water used to irrigate tiles is limited. + + TRUE + Water for irrigation is taken first from the deep soil + (groundwater) store, and then from the river storage when the + deep soil store is exhausted. Tiles are irrigated up to the + critical point if the necessary water is available. This option + requires :nml:mem:`JULES_IRRIG::l_irrig_dmd` = TRUE, + :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE, + :nml:mem:`JULES_RIVERS::l_rivers` = TRUE and + :nml:mem:`JULES_RIVERS::i_river_vn` = ``1,3``. + + .. warning:: + The irrigation supply code in JULES is still in development, + and is available in this release to support beta testing + activities. + + Users should ensure that results are as expected, and provide + feedback where deficiencies are identified. + + FALSE + Tiles will be irrigated to critical point from an unconstrained water supply. + + + This must be set to FALSE if :nml:mem:`JULES_WATER_RESOURCES::l_water_irrigation` = TRUE. + +.. nml:member:: irr_crop + + :type: integer + :permitted: 0, 1 or 2 + :default: 0 + + 0. Irrigation season (i.e. season in which crops might be growing + on the gridbox) lasts the entire year. + + 1. Irrigation season is determined from driving data according to + :ref:`Döll & Siebert (2002)` method. No irrigation + is applied outside the irrigation season. + + 2. Irrigation season is determined by maximum dvi across all + surface tiles. Requires :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0. No + irrigation is applied outside the irrigation season. + + +.. nml:member:: frac_irrig_all_tiles + + :type: logical + :default: T + + If T, then irrigation fraction is applied to all surface tiles, and F, it is applied only to the surface tiles specified in :nml:mem:`irrigtiles`. + + +.. nml:member:: set_irrfrac_on_irrtiles + + :type: logical + :default: F + + If F then irrigation is applied as an average across the gridbox and not to specific surface tiles. If T, then the irrigation fraction is only applied to the surface tile specified in :nml:mem:`irrigtiles`. Both :nml:mem:`frac_irrig_all_tiles` and :nml:mem:`set_irrfrac_on_irrtiles` cannot be set to T. + + +.. nml:member:: nirrtile + + :type: integer + :default: None + + The number of surface tiles to be irrigated. Only used if :nml:mem:`frac_irrig_all_tiles` = F. + + +.. nml:member:: irrigtiles + + :type: integer(nirrtile) + :default: None + + Indices of the surface tiles to be irrigated. Only used if :nml:mem:`frac_irrig_all_tiles` = F. + + +.. nml:member:: nstep_irrig + + :type: integer + :permitted: > 0 + :default: 86400/:nml:mem:`JULES_TIME::timestep_len` + + The number of model timesteps per irrigation update step + + Irrigation will be updated every :nml:mem:`nstep_irrig` timesteps. For example, with a model timestep of 1 hour, :nml:mem:`nstep_irrig` = 24 means that irrigation will be updated on the 24th timestep, i.e. daily updates. + + :nml:mem:`nstep_irrig` = NINT(frequency of irrigation update (in sec)) / :nml:mem:`JULES_TIME::timestep_len`) + + +.. _References_irrig: + +``JULES_IRRIG`` references +------------------------------- + +* Döll, P., and Siebert, S., Global modeling of irrigation water + requirements, Water Resour. Res., 38(4), + https://doi.org/10.1029/2001WR000355, 2002. diff --git a/doc/source/namelists/jules_prnt_control.nml.rst b/doc/source/namelists/jules_prnt_control.nml.rst new file mode 100644 index 00000000..212b331f --- /dev/null +++ b/doc/source/namelists/jules_prnt_control.nml.rst @@ -0,0 +1,27 @@ +``jules_prnt_control.nml`` +========================== + + +This file contains one namelist called :nml:lst:`JULES_PRNT_CONTROL`. + +This namelist sets options for output of diagnostic and informative messages. + +``JULES_PRNT_CONTROL`` namelist members +--------------------------------------- + +.. nml:namelist:: JULES_PRNT_CONTROL + +.. nml:member:: prnt_writers + + :type: integer + :permitted: 1,2 + :default: 1 + + Selects which tasks in a parallel job will write informative + output. + + = ========================================== + 1 All tasks write output + 2 Only the first task (Task 0) writes output + = ========================================== + diff --git a/doc/source/namelists/jules_radiation.nml.rst b/doc/source/namelists/jules_radiation.nml.rst new file mode 100644 index 00000000..964a4d5b --- /dev/null +++ b/doc/source/namelists/jules_radiation.nml.rst @@ -0,0 +1,310 @@ +``jules_radiation.nml`` +======================= + + +This file sets the radiation options. It contains one namelist called :nml:lst:`JULES_RADIATION`. + + + +``JULES_RADIATION`` namelist members +------------------------------------- + +.. nml:namelist:: JULES_RADIATION + +.. nml:member:: l_cosz + + :type: logical + :default: T + + Switch for calculation of solar zenith angle. + + TRUE + Calculate zenith angle. + + FALSE + Assume constant zenith angle of zero, meaning sun is directly overhead. + + n.b. assuming that the sun is directly overhead may overestimate primary productivity if :nml:mem:`JULES_VEGETATION::l_triffid` = TRUE (see GPP on :ref:`output_variables_section`). + + +.. nml:member:: l_spec_albedo + + :type: logical + :default: F + + Switch for the two-stream spectral land-surface albedo model. + + TRUE + Use spectral albedo with VIS and NIR components. + + FALSE + Use a single (averaged) waveband albedo. + + +.. nml:member:: l_spec_alb_bs + + :type: logical + :default: F + + Switch for albedo model, when spectral albedo is being used. + + Requires :nml:mem:`l_spec_albedo` = TRUE. + + TRUE + Produces a single albedo for use by both the direct and diffuse beams (a 'blue' sky albedo). This currently copies the diffuse beam albedo for the direct beam. + + FALSE + Produces both a direct ('black' sky) and a diffuse ('white' sky) albedo. + + +.. nml:member:: l_niso_direct + + :type: logical + :default: F + + Switch for using full non-isotropic expression for direct + scattering in plant canopies when using the two-stream canopy + radiation model. + + Requires :nml:mem:`l_spec_albedo` = TRUE. + + TRUE + Use full non-isotropic expression for scattering in plant canopies. + + FALSE + Use the original isotropic expression. + + +.. nml:member:: l_snow_albedo + + :type: logical + :default: F + + Switch for using prognostic snow properties, which represents the + effect of snow aging and soot deposition, in model albedo. + + Requires :nml:mem:`l_spec_albedo` = TRUE. + + TRUE + Use prognostic snow properties for albedo. + + FALSE + Calculate albedo of snow using only snow depth. + +.. nml:member:: l_embedded_snow + + :type: logical + :default: F + + Switch to account for pft LAI and pft height in calculation of snow albedo. + + TRUE + Use the embedded canopy snow albedo model. This is exclusive of :nml:mem:`JULES_RADIATION::l_snow_albedo`. + + FALSE + No effect. + +.. nml:member:: l_mask_snow_orog + + :type: logical + :default: F + + Switch for orographic masking of snow, which decreases the albedo + of snow in mountainous regions. + + TRUE + Include orographic masking of snow in calculating albedo. + + FALSE + No effect. + + +.. nml:member:: l_albedo_obs + + :type: logical + :default: F + + Switch for applying a scaling factor to the albedo values, on + surface tiles, so that the resultant aggregate albedo matches + observations. The supplied albedos should be from an observed + climatology or analysis system and be supplied via an ancillary + file. + + TRUE + Scale the albedo values on tiles within the physical limits + supplied in :nml:lst:`JULES_PFTPARM` and + :nml:lst:`JULES_NVEGPARM`. When + :nml:mem:`JULES_RADIATION::l_spec_albedo` = TRUE, VIS and NIR + components are required and when + :nml:mem:`JULES_RADIATION::l_spec_albedo` = FALSE the single + (averaged) waveband albedo is required. + + .. note:: Observed albedo(s) must be prescribed in + :doc:`prescribed_data.nml`. + + FALSE + Do not scale the albedo values on tiles. + +.. nml:member:: l_spec_sea_alb + + :type: logical + :default: F + + Switch to use spectrally varying open sea albedos + + TRUE + When :nml:mem:`JULES_RADIATION::i_sea_alb_method` = 1 or 2, + spectrally varying sea albedos are produced only when the spectral + file contains 6 SW bands identical to those used in HadGEM1. + + When :nml:mem:`JULES_RADIATION::i_sea_alb_method` = 3, the spectral + variability is calculated as per the Jin et al. (2011) + parameterisation. + + FALSE + Uses the calculated broadband sea albedo instead. + +.. nml:member:: i_sea_alb_method + + :type: integer + :default: None + + Choice of model for the Ocean Surface Albedo (open water, ice free) + + 1. Diffuse albedo constant (0.06), direct albedo from Briegleb and + Ramanathan (1982). + + 2. **'barker'** - Diffuse albedo constant (0.06), direct albedo from Barker and + Li (1995). + + 3. **'jin'** - Direct and diffuse albedo from Jin et al. (2011). + + 4. **'fixed'** - Fixed global value, defined by :nml:mem:`JULES_RADIATION::fixed_sea_albedo`. + + 5. Fixed global value, defined by + :nml:mem:`JULES_RADIATION::fixed_sea_albedo`, above 271K and + variable below this to simulate sea-ice following Liu et + al. (2007), Joshi & Haberle (2012) and Turbet et al. (2016). + +.. nml:member:: fixed_sea_albedo + + :type: real + :default: None + + The global value of sea albedo to use if :nml:mem:`JULES_RADIATION::i_sea_alb_method` = 4, 5 + +.. nml:member:: wght_alb + + :type: real(4) + :default: MDI + + Weights to form the overall albedo from its components (VIS direct, + VIS diffuse, NIR direct, NIR diffuse) + (Ideally, if :nml:mem:`JULES_RADIATION::l_partition_albsoil` = T, + :nml:mem:`JULES_RADIATION::wght_alb` and + :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` should be consistent, with + :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` equal to + :math:`\sum_{3,4}` + :nml:mem:`JULES_RADIATION::wght_alb` :math:`/ \sum_1^4` + :nml:mem:`JULES_RADIATION::wght_alb`. + However, :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` + is applied only to bare soil and having a single parameter + is more transparent to the user, while + :nml:mem:`JULES_RADIATION::wght_alb` + is used only in diagnostics in standalone JULES and may have + historical settings. Hence, the consistency of these two variables + is not enforced.) + +.. nml:member:: l_hapke_soil + + :type: logical + :default: F + + Switch to enable Hapke's model of soil albedo to include a zenith-angle + dependence + + TRUE + Apply a zenith-angle dependence to the direct albedo. + + FALSE + Use the diffuse albedo for the direct beam as well. + +.. nml:member:: l_partition_albsoil + + :type: logical + :default: F + + Switch to apply a spectral partitioning to the soil albedo. + + TRUE + Partition the soil albedo between the visible and near infrared parts + of the spectrum using :nml:mem:`JULES_RADIATION::ratio_albsoil` and + :nml:mem:`JULES_RADIATION::swdn_frac_albsoil`. + + FALSE + Apply the broadband albedo in both spectral regions. + +.. nml:member:: ratio_albsoil + + :type: real + :default: MDI + + Ratio of the NIR to the VIS albedo of bare soil. + Used if :nml:mem:`JULES_RADIATION::l_partition_albsoil` = T. + +.. nml:member:: swdn_frac_albsoil + + :type: real + :default: MDI + + The fraction of the total downward SW radiation assumed to be in the + NIR part of the spectrum for partitioning the soil albedo. + Used if :nml:mem:`JULES_RADIATION::l_partition_albsoil` = T. + (Ideally, :nml:mem:`JULES_RADIATION::wght_alb` and + :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` should be consistent, with + :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` equal to + :math:`\sum_{3,4}` + :nml:mem:`JULES_RADIATION::wght_alb` :math:`/ \sum_1^4` + :nml:mem:`JULES_RADIATION::wght_alb`. + However, :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` is applied + only to bare soil and having a single parameter is more transparent + to the user, while :nml:mem:`JULES_RADIATION::wght_alb` + is used only in diagnostics in standalone JULES and may have + historical settings. Hence, the consistency of these two variables + is not enforced.) + +.. seealso:: + References: + + * Barker, H.W. and Li, Z. (1995), Improved Simulation of Clear-Sky + Shortwave Radiative Transfer in the CCC-GCM. J. Climate, 8, + 2213–2223, `doi:10.1175/1520-0442(1995)008<2213:ISOCSS>2.0.CO;2 + `_ + * Briegleb, B. and Ramanathan, V. (1982), Spectral and Diurnal + Variations in Clear Sky Planetary Albedo. J. Appl. Meteor., 21, + 1160–1171, `doi:10.1175/1520-0450(1982)021<1160:SADVIC>2.0.CO;2 + `_ + * Liu, J. , Zhang, Z. , Inoue, J. and Horton, R. M. (2007), + Evaluation of snow/ice albedo parameterizations and their impacts + on sea ice simulations. Int. J. Climatol., 27: + 81-91. `doi:10.1002/joc.1373 + `_ + * Zhonghai Jin, Yanli Qiao, Yingjian Wang, Yonghua Fang, and + Weining Yi, "A new parameterization of spectral and broadband + ocean surface albedo", Opt. Express 19, 26429-26443 (2011), + `doi:10.1364/OE.19.026429 + `_ + * B. Hapke, "Bidirectional reflectance spectroscopy: 1. Theory", + J. Geophys. Res. 86(B4), 3039-3054 (1981), + `doi:10.1029/JB086iB04p03039 + `_ + * Manoj M. Joshi and + Robert M. Haberle. Astrobiology. Jan 2012. ahead of print + `doi:10.1089/ast.2011.0668 + `_ + * Martin Turbet, Jérémy Leconte, Franck Selsis, Emeline Bolmont, + François Forget, Ignasi Ribas, Sean N. Raymond and Guillem + Anglada-Escudé (2016), The habitability of Proxima Centauri + b - II. Possible climates and observability, A&A, 596, A112, + `doi:10.1051/0004-6361/201629577 + `_ diff --git a/doc/source/namelists/jules_rivers.nml.rst b/doc/source/namelists/jules_rivers.nml.rst new file mode 100644 index 00000000..5de34faa --- /dev/null +++ b/doc/source/namelists/jules_rivers.nml.rst @@ -0,0 +1,362 @@ +``jules_rivers.nml`` +==================== + +This file sets the river routing options. It contains two namelists called :nml:lst:`JULES_RIVERS` and :nml:lst:`JULES_OVERBANK`. + +River routing introduces two more grids to a JULES run: the river routing input grid and the river routing model grid. The river routing input grid must always be specified as a 2D grid in :nml:lst:`JULES_RIVERS_PROPS`. This is not required to be identical to the input or the model grid. Internally the model compresses this to the river routing model grid, which is a 1D grid with length ``np_rivers``, which is the number of valid routing points in the river routing input grid. All river routing output will be on the river routing model grid, or will be regridded to the model grid. + +.. note:: + The river routing code in JULES is still in development. Users should ensure that results are as expected, and provide feedback where deficiencies are identified. + + +``JULES_RIVERS`` namelist members +--------------------------------- + +.. nml:namelist:: JULES_RIVERS + +.. nml:member:: l_rivers + + :type: logical + :default: F + + Switch for enabling river routing. + + TRUE + Use the river routing algorithm specified by :nml:mem:`i_river_vn` to route runoff along river pathways. + + FALSE + No river routing. + + +.. nml:member:: i_river_vn + + :type: integer + :default: None + + Switch to select the river routing algorithm to use for river routing. + + ``1`` + Use a UM-coupled JULES implementation of the TRIP model (see Oki et al. 1999). This value is not allowed in standalone JULES + + ``2`` + Use a standalone or UM-coupled JULES implementation of the RFM kinematic wave model (see Dadson and Bell 2010, Bell et al. 2007). + + ``3`` + Use a standalone JULES implementation of the TRIP model (see Oki et al. 1999). + +.. nml:member:: l_riv_overbank + + :type: logical + :default: F + + Switch for enabling river overbank inundation. Only used if :nml:mem:`JULES_RIVERS::l_rivers` is TRUE. + + TRUE + Calculate frac_fplain_lp, i.e. overbank inundation area as a fraction of gridcell area. + + FALSE + No overbank inundation calculations + +.. note:: + If :nml:mem:`JULES_RIVERS::l_riv_overbank` = FALSE, then optional namelist :nml:lst:`JULES_OVERBANK` is not required. + + +.. nml:member:: nstep_rivers + + :type: integer + :permitted: > 0 + :default: None + + The number of model timesteps per routing timestep. + + For example, :nml:mem:`nstep_rivers` = 5 means that runoff will be accumulated for 5 model timesteps before being routed on the 5th timestep. + + +.. warning:: + The river routing parameter values can be highly dependent on model resolution, so care is required by the user to ensure that appropriate values are selected, tested and adjusted as required. + + Suggested values for global and high-resolution runs are listed below, however these should be treated as a starting point only. + + +.. nml:group:: RFM parameters - used if :nml:mem:`i_river_vn` = ``2`` + + .. nml:member:: a_thresh + + :type: integer + :default: None + :suggested: 1 (spatial resolution coarser than 20 km gridcells), ~10 (high-resolution) + + The threshold drainage area (specified in number of cells) draining to a gridbox, above which the grid cell is considered to be a river point (see a_T in Bell et al. 2007:541). + + Remaining points are treated as land (drainage area = 0) or sea (drainage area < 0). See Bell et al. (2007). + + + .. nml:member:: cland + + :type: real + :permitted: > 0 + :default: None + :suggested: 0.20 m/s (global), 0.40 m/s (1 km resolution, Bell et al. 2007) + + The land wave speed (kinematic wave speed for surface flow in a land grid box on the river routing grid, m s\ :sup:`-1`). This is the speed at which water moves through surface soil in a non-river grid cell (even without major rivers, there are always minor water courses so these cells do still contribute flow to neighbouring cells). + + + .. nml:member:: criver + + :type: real + :permitted: > 0 + :default: None + :suggested: 0.62 m/s (global), 0.50 m/s (1 km resolution, Bell et al. 2007) + + The river wave speed (kinematic wave speed for surface flow in a river grid box on the river routing grid, m s\ :sup:`-1`). This value should be close to the :nml:mem:`rivers_speed` used by TRIP, but not identical because RFM makes different assumptions about e.g. meandering. + + + .. nml:member:: cbland + + :type: real + :permitted: > 0 + :default: None + :suggested: <= :nml:mem:`cland`. 0.10 m/s (global), 0.05 m/s (1 km resolution, Bell et al. 2007) + + The subsurface land wave speed (kinematic wave speed for subsurface flow in a land grid box on the river routing grid, m s\ :sup:`-1`). + + + .. nml:member:: cbriver + + :type: real + :permitted: > 0 + :default: None + :suggested: <= :nml:mem:`criver`. 0.15 m/s (global), 0.05 m/s (1 km resolution, Bell et al. 2007) + + The subsurface river wave speed (kinematic wave speed for subsurface flow in a river grid box on the river routing grid, m s\ :sup:`-1`). + + + .. nml:member:: retl + + :type: real + :permitted: -1 to 1 + :default: None + :suggested: 0.005 (1 km resolution, Bell et al. 2007) + + The (resolution dependent) land return flow fraction. Bell et al. (2007:Table1) suggested value 0.005. On non-river grid cells in the land mask: if retl>0 then fraction retl of the subsurface flow moves to the surface per routing timestep; if retl<0 then fraction retl of the surface flow moves to the subsurface per routing timestep. + + + .. nml:member:: retr + + :type: real + :permitted: -1 to 1 + :default: None + :suggested: 0.005 (1 km resolution, Bell et al. 2007) + + The (resolution dependent) river return flow fraction. On river grid cells in the land mask: if retr>0 then fraction retr of the subsurface flow moves to the surface per routing timestep; if retr<0 then fraction retr of the surface flow moves to the subsurface per routing timestep. + + + .. nml:member:: runoff_factor + + :type: real + :permitted: > 0 + :default: None + + Values !=1.0 are generally used to correct biases in precipitation when the model is forced with observed data **It is highly recommended that this is set to 1.0 (i.e. no runoff adjustment).** + + +.. nml:group:: TRIP parameters - used if :nml:mem:`i_river_vn` = ``1,3`` + + .. nml:member:: rivers_speed + + :type: real + :permitted: > 0 + :default: None + + The effective river velocity (m s\ :sup:`-1`). See Oki et al. (1999). :nml:mem:`rivers_speed` should equal (river flow velocity / :nml:mem:`rivers_meander`). A value of 0.4 can be used, while Oki et al. (1999) used a value of 0.5. + + + .. nml:member:: rivers_meander + + :type: real + :permitted: > 0 + :default: None + + 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 for UM-TRIP only - i.e. only used if :nml:mem:`i_river_vn` = ``1`` + + .. nml:member:: lake_water_conserve_method + + :type: integer + :default: 1 + + Selects different fields for use in water conservation of lake evaporation + + ``1`` + fqw_surft: This is the moisture flux on each tile, in which case the inland water tile is used. Snow sublimation has already been removed from fqw_surft at the point in the code that this is used. + + ``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: + + * Arora VK & Boer GJ (2012). A variable velocity flow routing algorithm for GCMs. Journal of Geophysical Research D 104:30965-30979. + * Bell, V.A. et al. (2007) Development of a high resolution grid-based river flow model for use with regional climate model output. Hydrology and Earth System Sciences. 11 532-549 + * Dadson, S.J. and Bell, V.A. (2010) Comparison of Grid-2-Grid and TRIP runoff routing schemes. Centre for Ecology & Hydrology Internal Report http://nora.nerc.ac.uk/10890/1/dadson_etal_2010_g2gtrip.pdf + * Dadson S.J. et al. (2011) Evaluation of a grid-based river flow model configured for use in a regional climate model. Journal of Hydrology. 411 238-250 + * Falloon, P.D. et al (2007) New global river routing scheme in the Unified Model. Hadley Centre Technical Note 72, available from `the Met Office Library `_. + * Jones R., Dadson, S. and Bell, V.A. (2007) Report on European grid-based river-flow modelling for application to Regional Climate Models. Met Office Hadley Centre deliverable report. + * Oki, T. and Sud, Y.C. (1998) Design of Total Runoff Integrating Pathways (TRIP)—A Global River Channel Network. Earth Interactions, 2: 1-37. + * Oki, T., et al (1999) Assessment of annual runoff from land surface models using Total Runoff Integrating Pathways (TRIP). Journal of the Meteorological Society of Japan. 77 235-255 + + + +``JULES_OVERBANK`` namelist members +----------------------------------- + +.. nml:namelist:: JULES_OVERBANK + +.. warning:: + The overbank inundation parameter values can be highly dependent on model resolution, so care is required by the user to ensure that appropriate values are selected, tested and adjusted as required. + + Suggested values for global and high-resolution runs are listed below, however these should be treated as a starting point only. + +.. nml:member:: l_riv_overbank + + :type: logical + :default: F + + Switch for enabling river overbank inundation. Only used if :nml:mem:`JULES_RIVERS::l_rivers` is TRUE. + + TRUE + Calculate overbank inundation area as a fraction of gridcell area. + + FALSE + No overbank inundation calculations + +.. note:: + If :nml:mem:`l_riv_overbank` = FALSE, no further variables are needed from this namelist. + +.. nml:member:: overbank_model + + :type: integer + :permitted: 1, 2, 3 + :default: none + + Choice of model of overbank inundation. + + 1. Simple model using an allometric (scaling) relationship to estimate river width, without use of + topographic data. + + 2. Simple model using allometric relationships to estimate river width and depth, and the + Rosgen (1994) entrenchment ratio, without use of topographic data. When river flow rates are + higher than the estimated bankfull flow, river width is constrained so that when river + depth = 2 x bankfull depth then width = :nml:mem:`ent_ratio` * bankfull width. + + 3. The inundated area is calculated using a hypsometric integral based on a lognormal area-altitude + distribution and an allometric relationship to estimate river depth. + The parameters of the lognormal distribution are specified via :nml:lst:`JULES_RIVERS_PROPS`. + (**This is the recommended approach.**) + + +.. nml:group:: River depth allometry (used if :nml:mem:`overbank_model` = 2 or 3) + + Allometry is: (DEPTH in m) = :nml:mem:`riv_c` * ( (SURFACE RIVER INFLOW in m3 s\ :sup:`-1`) ^ :nml:mem:`riv_f`) (Leopold & Maddock 1953:eqn2) + + + .. nml:member:: riv_c + + :type: real + :default: none + :permitted: >=0 and <=(1/:nml:mem:`riv_a`) + :suggested: 0.27 (global, from Andreadis et al. 2013) + + Coefficient in the allometry for river depth (units are (m / ((m3/s)^riv_f)), i.e. dependent on the value of riv_f) + + + .. nml:member:: riv_f + + :type: real + :default: none + :permitted: >=0 and <=(1-:nml:mem:`riv_b`) + :suggested: 0.30 (global, from Andreadis et al. 2013) + + Exponent in the allometry for river depth (dimensionless) + + +.. nml:group:: River width scaling (used if :nml:mem:`overbank_model` = 1 or 2) + + .. nml:group:: River width allometry + + Allometry is: (WIDTH in m) = :nml:mem:`riv_a` * ( (SURFACE RIVER INFLOW in m3 s\ :sup:`-1`) ^ :nml:mem:`riv_b`) (Leopold & Maddock 1953:eqn1) + + + .. nml:member:: riv_a + + :type: real + :default: none + :permitted: >=0 and <=(1/:nml:mem:`riv_c`) + :suggested: 7.20 (global, from Andreadis et al. 2013) + + Coefficient in the allometry for river width (units are (m / ((m3/s)^riv_b)), i.e. dependent on the value of riv_b) + + + .. nml:member:: riv_b + + :type: real + :default: none + :permitted: >=0 and <=(1-:nml:mem:`riv_f`) + :suggested: 0.50 (global, from Andreadis et al. 2013) + + Exponent in the allometry for river width (dimensionless) + + + .. nml:group:: Bankfull flow allometry (used if :nml:mem:`overbank_model` = 2) + + Allometry is: (BANKFULL DISCHARGE RATE QBF in m3 s\ :sup:`-1`) = :nml:mem:`coef_b` * ( (CONTRIBUTING AREA in km2) ^ :nml:mem:`exp_c` ) (see e.g. Andreadis et al. 2013) + + + .. nml:member:: coef_b + + :type: real + :default: none + :suggested: 0.08 (for "several drainages in western Washington State, USA", Cragun 2005) + + Coefficient in the allometry for bankfull flow (see Sen 2018:eqn3.33). + + + .. nml:member:: exp_c + + :type: real + :default: none + :suggested: 0.95 (for "several drainages in western Washington State, USA", Cragun 2005) + + Exponent in the allometry for bankfull flow (see Sen 2018:eqn3.33). + + + .. nml:member:: ent_ratio + + :type: real + :default: none + + The Rosgen entrenchment ratio (single value for all water courses in the simulation): when river depth = 2 x bankfull depth then width = :nml:mem:`ent_ratio` * bankfull width (i.e. :nml:mem:`ent_ratio` can be used to specify how wide floodplains are allowed to be). + + +.. seealso:: + References: + + * Andreadis KM, Schumann GJ & Pavelsky T (2013). A simple global river bankfull width and depth database. Water Resources Research 49:7164-7168 + * Cragun WS (2005). Discharge-Area relations from Selected Drainages on the Colorado Plateau: A GIS Application. Utah State University, http://hydrology.usu.edu/giswr/archive05/scragun/termproject/ + * Leopold LB & Maddock T (1953). The Hydraulic Geometry of Stream Channels and Some Physiographic Implications. United States Geological Survey Professional Papers 252:1-57 + * Rosgen DL (1994). A classification of natural rivers. Catena 22:169-199. + * Sen Z (2018). Flood Modeling, Prediction and Mitigation. Springer. diff --git a/doc/source/namelists/jules_snow.nml.rst b/doc/source/namelists/jules_snow.nml.rst new file mode 100644 index 00000000..f842fb31 --- /dev/null +++ b/doc/source/namelists/jules_snow.nml.rst @@ -0,0 +1,648 @@ +``jules_snow.nml`` +================== + + +This file sets the snow options and parameters. It contains one namelist called :nml:lst:`JULES_SNOW`. + + + +``JULES_SNOW`` namelist members +------------------------------- + +HCTN30 refers to Hadley Centre technical note 30, available from `the Met Office Library `_. + + +.. nml:namelist:: JULES_SNOW + +.. nml:member:: nsmax + + :type: integer + :permitted: >= 0 + :default: 0 + + Maximum possible number of snow layers. + + 0 + A composite soil/snow layer is used. This value gives the behaviour found in JULES2.0 and earlier. + + > 0 + The state of up to ``nsmax`` separate snow layers is modelled. Values of ``nsmax = 3`` or more are recommended. + + +.. nml:member:: l_snowdep_surf + + :type: logical + :default: F + + TRUE + Use equivalent canopy snow depth for surface calculations on surface tiles with a snow canopy. + + FALSE + No effect. + + +.. nml:member:: frac_snow_subl_melt + + :type: integer + :permitted: 0 or 1 + :default: 0 + + Switch for use of snow-cover fraction in the calculation of sublimation and melting. + + 0. Off + 1. On + + +.. nml:member:: graupel_options + + :type: integer + :permitted: 0, 1 or 2 + :default: 0 + + Switch for treatment of graupel in the snow scheme + + 0. Include graupel as snowfall + 1. Ignore graupel in the surface snowfall + 2. Treat graupel separately + + Always "Include graupel as snowfall" (option 0) in standalone JULES because + separate snow and graupel driving data are not available. + If graupel is included in the UM surface snowfall diagnostic + then JULES can either include this graupel as snow in the surface scheme (option 0), + ignore this graupel completely, thereby breaking conservation + of water and energy in the coupled land-atmosphere model (option 1) or + treat graupel separately (currently this only means allowing graupel to + fall straight through the canopy) + + +.. nml:member:: dzsnow + + :type: real(nsmax) + :default: None + + Prescribed thickness of each snow layer (m). + + Only used if :nml:mem:`nsmax` > 0. + + The interpretation of ``dzsnow`` is slightly complicated and an example of the evolution of the snow layers is given below. + + ``dzsnow`` gives the thickness of each layer when it is not the bottom layer. + + For the top layer, the minimum thickness is ``dzsnow(1)`` and the maximum thickness is ``2 * dzsnow(1)``. For all other layers ``iz``, the minimum thickness is ``dzsnow(iz - 1)``, i.e. the given thickness of the previous layer, and the maximum thickness is ``2 * dzsnow(iz)``, i.e. twice the layer ``dzsnow`` value, except for the last possible layer (:nml:mem:`nsmax`) which has no upper limit. + + As a snowpack deepens, the bottom layer (closest to the soil; label this as layer ``b``) thickens until it reaches its maximum allowed thickness, at which point it will split into a layer of depth ``dzsnow(b)`` and a new bottom layer ``b + 1`` is added to hold the remaining snow. If a layer becomes thinner than its value in ``dzsnow`` it is removed and the snow partitioned between the remaining layers. Whenever a layer splits or is removed, the properties of the layer (e.g. temperature) are allocated to the remaining layers. + + Note that ``dzsnow(nsmax)``, the final thickness, is not used but a value must be input. + + +.. nml:member:: cansnowpft + + :type: logical(npft) + :default: F + + Flag indicating whether snow can be held under the canopy of each PFT. + + Only used if :nml:mem:`JULES_VEGETATION::can_model` = 4. + + The model of snow under the canopy is currently only suitable for trees. + + TRUE + Snow can be held under the canopy. + + FALSE + Snow cannot be held under the canopy. + + +.. nml:group:: Radiation parameters + + .. nml:member:: r0 + + :type: real + :default: 50.0 + + Grain size for fresh snow (\ |mu|\ m). + + Only used if :nml:mem:`JULES_RADIATION::l_snow_albedo` = TRUE or :nml:mem:`JULES_RADIATION::l_embedded_snow` = TRUE. + + + .. nml:member:: rmax + + :type: real + :default: 2000.0 + + Maximum snow grain size (\ |mu|\ m). + + Only used if :nml:mem:`JULES_RADIATION::l_snow_albedo` = TRUE or :nml:mem:`JULES_RADIATION::l_embedded_snow` = TRUE. + + + .. nml:member:: snow_ggr + + :type: real(3) + :default: 0.6, 0.06, 0.23e6 + + Snow grain area growth rates (\ |mu|\ m\ :sup:`2` s\ :sup:`-1`). + + Only used if :nml:mem:`JULES_RADIATION::l_snow_albedo` = TRUE or + :nml:mem:`JULES_RADIATION::l_embedded_snow` = TRUE, and requires + a snow grain size to calculate the albedo. + + The three values are for melting snow, cold fresh snow and cold + aged snow respectively, the use of which depends on the setting + :nml:mem:`i_grain_growth_opt` as follows: + + ============================= ========================= ================================================================= + :nml:mem:`i_grain_growth_opt` Growth rates used Notes + ============================= ========================= ================================================================= + 0 :nml:mem:`snow_ggr` (1:3) Uses all values; melting snow, cold fresh snow and cold aged snow + 1 :nml:mem:`snow_ggr` (1) Uses values for melting snow only. + + For cold snow a separate scheme is used following + :ref:`Taillandier et al. (2007)`, where the + parameters are currently hard-wired. + ============================= ========================= ================================================================= + + + .. nml:member:: amax + + :type: real(2) + :default: 0.98, 0.7 + + Maximum albedo for fresh snow. + + Only used if :nml:mem:`JULES_RADIATION::l_snow_albedo` or + :nml:mem:`JULES_SURFACE::l_elev_land_ice` is TRUE. + + Values 1 and 2 are for VIS and NIR wavebands respectively. + + When: + + :nml:mem:`JULES_RADIATION::l_snow_albedo` = TRUE + These parameters are used as limits at all snow-covered + grid points. + + :nml:mem:`JULES_RADIATION::l_embedded_snow` = TRUE + These parameters are not used. + + :nml:mem:`JULES_SURFACE::l_elev_land_ice` = TRUE + Irrespective of whether either of the two previous options + are selected, these parameters are used to adjust the albedo + of dense snow to a value more appropriate for firn. See + also :nml:mem:`aicemax`. + + + .. nml:member:: aicemax + + :type: real(2) + :default: 0.78, 0.36 + + Maximum albedo for bare ice + + Only used if :nml:mem:`JULES_SURFACE::l_elev_land_ice` = + TRUE. See also :nml:mem:`rho_firn_albedo`. + + Values 1 and 2 are for VIS and NIR wavebands respectively. + + + .. nml:member:: maskd + + :type: real + :default: 50.0 + + Used in the calculation of the weighting factor for snow in the + setting of the overall surface albedo, the surface resistance + and surface melting. It represents the inverse of the e-folding + depth for masking by snow. A higher value indicates that masking + by snow is more effective. + + N.B. This was originally used to multiply the snow mass (with a + standard value of 0.2), but is now used to multiply the snow + depth. + + + .. nml:member:: dtland + + :type: real + :default: 2.0 + + Degrees Celsius below zero at which snow albedo equals cold deep snow albedo. + + This is used only if the diagnostic snow albedo scheme is + selected, i.e. if :nml:mem:`JULES_RADIATION::l_snow_albedo` = + FALSE and :nml:mem:`JULES_RADIATION::l_embedded_snow` = + FALSE. This is 2.0 in HCTN30 Eq4. + + Must not be zero. + + + .. nml:member:: kland_numerator + + :type: real + :default: 0.3 + + Used in snow-ageing effect on albedo. + + This is used only if the diagnostic snow albedo scheme is + selected, i.e. if :nml:mem:`JULES_RADIATION::l_snow_albedo` = + FALSE and :nml:mem:`JULES_RADIATION::l_embedded_snow` = + FALSE. This is 2.0 in HCTN30 Eq4. + + ``kland`` is computed by dividing this value by + :nml:mem:`dtland` - see HCTN30 Eq4. + + + .. nml:member:: can_clump + + :type: real(npft) + :default: MDI + + Clumping parameter for snow on the canopy in calculation of albedo. + + Only used if :nml:mem:`JULES_VEGETATION::can_model` = 4, + :nml:mem:`JULES_RADIATION::l_embedded_snow` = TRUE and + :nml:mem:`cansnowpft` = TRUE on that surface tile. + + The model of snow under the canopy is currently only suitable + for trees. + + The inverse of this parameter specifies the fraction of the + canopy over which snow is distributed when calculating the + albedo. It should not be less than 1 and higher values indicate + that snow on a canopy is more clumped, leaving more of the bare + canopy exposed. + + + .. nml:member:: n_lai_exposed + + :type: real(npft) + :default: MDI + + LAI distribution parameter for calculation of snow albedo. + + A power-law distribution of leaf area density is assumed within + the canopy for calculating masking of snow by vegetation using + the embedded scheme. Higher values indicate that snow is more + effective in covering vegetation. + + Only used if :nml:mem:`JULES_RADIATION::l_embedded_snow` = TRUE. + + + .. nml:member:: lai_alb_lim_sn + + :type: real(npft) + :default: MDI + + Minimum LAI in calculation of albedo in the presence of snow. + + A minimum LAI is imposed when calculating the albedo of plant + canopies (historically 0.5). This parameter allows it to be set + for each PFT in the presence of snow. Crudely, it represents the + stem area of vegetation remaining when the true LAI is 0. A + separate variable, :nml:mem:`JULES_PFTPARM::lai_alb_lim_io` is + used in the absence of snow. + + +.. nml:group:: Other snow parameters + + .. nml:member:: rho_snow_const + + :type: real + :default: 250.0 + + Constant density of lying snow (kg m\ :sup:`-3`). + + If :nml:mem:`nsmax` = 0, snow is modelled as a single layer of + constant density using this value. + + If :nml:mem:`nsmax` > 0, snow density is prognostic, except for + snow on the canopy when :nml:mem:`cansnowpft` is TRUE, and for + thin layers of snow when :nml:mem:`nsmax` > 0. + + + .. nml:member:: rho_snow_fresh + + :type: real + :default: 100.0 + + Density of fresh snow (kg m\ :sup:`-3`). + + Only used if :nml:mem:`nsmax` > 0. + + .. nml:member:: rho_firn_albedo + + :type: real + :default: 550.0 + + Only used if :nml:mem:`JULES_SURFACE::l_elev_land_ice` = TRUE. + + This is the threshold density (as measured over the ~top 10 cm, + depending on how the :nml:mem:`dzsnow` layers are specified) at + which the grain-size calculation of prognostic snow albedo will + switch to one dependent on the surface density of the + snowpack. Albedo is linearly scaled between :nml:mem:`amax` for + :nml:mem:`rho_snow_const` and :nml:mem:`aicemax` for density the + of ice (917 kg m\ :sup:`-3`). + + + .. nml:member:: snow_hcon + + :type: real + :default: 0.265 + + Thermal conductivity of lying snow (W m\ :sup:`-1` K\ + :sup:`-1`). + + This value is used for all snow if :nml:mem:`nsmax` = 0, but only + for thin snow if :nml:mem:`nsmax` > 0. See HCTN30 Eq.42. for its + application. + + + .. nml:member:: snow_hcap + + :type: real + :default: 0.63e6 + + Thermal capacity of lying snow (J K\ :sup:`-1` m\ :sup:`-3`). + + + .. nml:member:: snowliqcap + + :type: real + :default: 0.05 + + Liquid water holding capacity of lying snow, as a fraction of snow mass. + + Only used if :nml:mem:`nsmax` > 0. + + + .. nml:member:: snowinterceptfact + + :type: real + :default: 0.7 + + Constant in relationship between mass of intercepted snow and snowfall rate. + + Only used if :nml:mem:`JULES_VEGETATION::can_model` = 4. + + + .. nml:member:: snowloadlai + + :type: real + :default: 4.4 + + Ratio of maximum canopy snow load to leaf area index (kg m\ :sup:`-2`). + + Only used if :nml:mem:`JULES_VEGETATION::can_model` = 4. + + + .. nml:member:: snowunloadfact + + :type: real + :default: 0.4 + + Constant in relationship between canopy snow unloading and canopy snow melt rate. + + Only used if :nml:mem:`JULES_VEGETATION::can_model` = 4. + + + .. nml:member:: unload_rate_cnst + + :type: real(npft) + :default: MDI + + Constant term in the background unloading rate for snow on the + canopy. Snow is unloaded from the canopy as a background process + or because it is melting. + + Only used if :nml:mem:`JULES_VEGETATION::can_model` = 4 and + :nml:mem:`cansnowpft` = TRUE on that surface tile. + + + .. nml:member:: unload_rate_u + + :type: real(npft) + :default: MDI + + Term proportional to wind speed in the background unloading rate + for snow on the canopy. + + Only used if :nml:mem:`JULES_VEGETATION::can_model` = 4 and + :nml:mem:`cansnowpft` = TRUE on that surface tile. + + + .. nml:member:: i_snow_cond_parm + + :type: integer + :permitted: 0 or 1 + :default: MDI + + Scheme used to calculate the conductivity of snow + + Only used if :nml:mem:`nsmax` > 0. + + Two parametrizations of snow conductivity are available + taken from the papers of :ref:`Yen (1981)` and + :ref:`Calonne et al. (2011)`. + + 0. :ref:`Yen (1981)` + 1. :ref:`Calonne et al. (2011)` + + + .. nml:member:: l_et_metamorph + + :type: logical + :default: F + + This parametrization follows the form used by e.g. :ref:`Dutra + et al. (2010)`. + + Only used if :nml:mem:`nsmax` > 0. + + TRUE + Include the effect of thermal metamorphism on the snow density. + + FALSE + No effect. + + + .. nml:member:: l_snow_infilt + + :type: logical + :default: F + + Only used if :nml:mem:`nsmax` > 0. + + TRUE + Pass rainfall and melting from the canopy to the snowpack as + infiltration. + + FALSE + No effect. + + + .. nml:member:: l_snow_nocan_hc + + :type: logical + :default: F + + Only used if :nml:mem:`nsmax` > 0. + + TRUE + Do not include the canopy heat capacity in the surface energy balance at the top of the snow pack on surface tiles without a canopy snow model. + + FALSE + The canopy heat capacity is included in the surface energy balance at the top of the snow pack. + + + .. nml:member:: a_snow_et + + :type: real + :default: MDI + + Constant in parametrization of thermal metamorphism. + + Only used if :nml:mem:`l_et_metamorph` = TRUE. + + .. nml:member:: b_snow_et + + :type: real + :default: MDI + + Constant in parametrization of thermal metamorphism. + + Only used if :nml:mem:`l_et_metamorph` = TRUE. + + .. nml:member:: c_snow_et + + :type: real + :default: MDI + + Constant in parametrization of thermal metamorphism. + + Only used if :nml:mem:`l_et_metamorph` = TRUE. + + .. nml:member:: rho_snow_et_crit + + :type: real + :default: MDI + + Critical density in parametrization of thermal metamorphism. + + Only used if :nml:mem:`l_et_metamorph` = TRUE. + + + .. nml:member:: i_grain_growth_opt + + :type: integer + :permitted: 0 or 1 + :default: 0 + + Scheme used to calculate the rate of growth of snow grains. + + 0. Invokes the original scheme based on :ref:`Marshall + (1989)`, with no dependence of the rate of + growth of small grains on the temperature. + + 1. Invokes the scheme for growth of snow grains proposed by + :ref:`Taillandier et al. (2007)` for + equitemperature metamorphism. Growth is significantly + slower than the default scheme at low temperatures. + + + .. nml:member:: i_relayer_opt + + :type: integer + :permitted: 0 or 1 + :default: 0 + + Scheme used to relayer the snowpack. + + Only used if :nml:mem:`nsmax` > 0. + + 0. Invokes the original scheme with relayering of the grain size + involving the grain size itself. + 1. Relayering is done using the inverse of the grain size. This + is more consistent with conserving the specific surface area + of snow, though full conservation would require mass + weighting to be invoked during regridding. + + + .. nml:member:: i_basal_melting_opt + + :type: integer + :permitted: 0 or 1 + :default: 0 + + Option to treat basal melting of the snow pack. + + When snow falls on warm ground, it will melt from the base of + the snowpack, where the temperature of the snow will rise to the + melting point. The 0-layer snow scheme, which is used for thin + snow even when the multilayer scheme is selected, did not + represent this process and included only melting at the surface. + + 0. Default: Basal melting is omitted. + 1. Basal melting takes place instantaneously if the temperature + of the first soil layer is above freezing, until the snow is + removed or the temperature of soil layer is reduced to + freezing. + + + + + +Example of the evolution of snow layer thickness +------------------------------------------------ + +The table below gives an example of how the number and thickness of snow layers varies with total snow depth for the case of :nml:mem:`nsmax` = 3 and ``dzsnow = (0.1, 0.15, 0.2)``. Note that if the values given by the user for :nml:mem:`dzsnow` are a decreasing series with ``dzsnow(i) <= 2 * dzsnow(i - 1)``, the algorithm will result in layers ``i`` and ``i + 1`` being added at the same time. Don't panic - this should not be a problem for the simulation. + +.. tabularcolumns:: |p{3cm}|p{1.5cm}|p{3cm}|p{7cm}| + ++--------------------+-----------+----------------------+---------------------------------------------------------------------------------+ +| Snow depth (m) | Number | Layer thickness, | Comments | +| | of layers | uppermost layer | | +| | | first (m) | | ++====================+===========+======================+=================================================================================+ +| ``d < 0.1`` | 0 | | While the depth of snow is less than ``dzsnow(1)``, the layer model is not | +| | | | active and snow and soil are combined in a composite layer. | ++--------------------+-----------+----------------------+---------------------------------------------------------------------------------+ +| ``0.1 <= d < 0.2`` | 1 | Total snow depth | The single layer grows until it is twice as thick as ``dzsnow(1)``. | ++--------------------+-----------+----------------------+---------------------------------------------------------------------------------+ +| ``0.2 <= d < 0.4`` | 2 | 0.1, remainder | Above 0.2m, the single layer splits into a top layer of 0.1m and the remaining | +| | | | snow in the bottom layer. | ++--------------------+-----------+----------------------+---------------------------------------------------------------------------------+ +| ``>= 0.4`` | 3 | 0.1, 0.15, remainder | At 0.4m depth, layer 2 (which has grown to 0.3m thick, i.e. ``2 * dzsnow(2)``), | +| | | | splits into a layer of 0.15m and a new bottom layer holding the the remaining | +| | | | 0.15m. As all layers are now in use, any subsequent deepening of the pack is | +| | | | dealt with by increasing the thickness in this bottom layer. | ++--------------------+-----------+----------------------+---------------------------------------------------------------------------------+ + + + +.. |mu| unicode:: μ .. u + +.. _References_snow: + +``JULES_SNOW`` references +------------------------------- + +* Calonne, N., Flin, F., Morin, S., Lesaffre, B., du + Roscoat, S. Rolland, and Geindreau, C. (2011). Numerical and + experimental investigations of the effective thermal conductivity of + snow, Geophys. Res. Lett., 38, L23501, + https://doi.org/10.1029/2011GL049234. +* Dutra, E., Balsamo, G., Viterbo, P., Miranda, P. M., Beljaars, A., + Schar, C., and Elder, K. (2010). An improved snow scheme for the ECMWF land + surface model: Description and offline validation, J. Hydrometeorol., + 11, 899–916, https://doi.org/10.1175/2010JHM1249.1. +* Marshall, S.E. (1989). A physical parameterization of snow albedo for + use in climate models. NCAR Cooperative Thesis 123. Boulder, CO : + National Center for Atmospheric + Research. https://atmos.washington.edu/~sgw/PAPERS/1989_Marshall.pdf +* Taillandier, A.-S., F. Domine, W. R. Simpson, M. Sturm, + and T. A. Douglas (2007). Rate of decrease of the specific surface + area of dry snow: Isothermal and temperature gradient + conditions, J. Geophys. Res., 112, F03003, + https://doi.org/10.1029/2006JF000514. +* Yen, Y.-C. (1981). Review of thermal properties of snow, ice and sea + ice. Cold Regions Research and Engineering Laboratory (CRREL) Report + 81-10. https://hdl.handle.net/11681/9469 diff --git a/doc/source/namelists/jules_soil.nml.rst b/doc/source/namelists/jules_soil.nml.rst new file mode 100644 index 00000000..e07ceaf0 --- /dev/null +++ b/doc/source/namelists/jules_soil.nml.rst @@ -0,0 +1,244 @@ +``jules_soil.nml`` +================== + + +This file sets the soil options and parameters. It contains one namelist called :nml:lst:`JULES_SOIL`. + + + +``JULES_SOIL`` namelist members +------------------------------- + +.. nml:namelist:: JULES_SOIL + +.. nml:member:: sm_levels + + :type: integer + :permitted: >= 1 + :default: 4 + + Number of soil layers. + + A value of 4 is often used, with soil layer depths that have been tuned using this. + + .. warning:: + If :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0, ``sm_levels >= 3`` is required. + + +.. nml:member:: l_vg_soil + + :type: logical + :default: F + + Switch for van Genuchten soil hydraulic model. + + TRUE + Use van Genuchten model. + + FALSE + Use Brooks and Corey model [#]_. + + .. seealso:: + References: + + * Brooks, R.H. and A.T. Corey, 1964, Hydraulic properties of porous media. Colorado State University Hydrology Papers 3. + * van Genuchten, M.T., 1980, A Closed-form Equation for Predicting the Hydraulic Conductivity of Unsaturated Soils. Soil Science Society of America Journal, 44:892-898. + + +.. nml:member:: l_dpsids_dsdz + + :type: logical + :default: F + + Switch to calculate vertical gradient of soil suction with the assumption of linearity only for fractional saturation (consistent with the calculation of hydraulic conductivity). + + +.. nml:member:: l_soil_sat_down + + :type: logical + :default: F + + Switch for dealing with supersaturated soil layers. If a soil layer becomes supersaturated, the water in excess of saturation will be put into the layer below or above according to this switch. + + TRUE (Down) + Any excess is put into the layer below. Any excess from the bottom + layer becomes subsurface runoff. + + FALSE (Up) + Any excess is put into the layer above. Any excess from the top layer becomes surface runoff. This option was used in JULES2.0. + +.. nml:member:: l_holdwater + + :type: logical + :default: F + + This switch fixes a problem in soil hydrology, whereby if a layer goes supersaturated during the implicit calulation, the excess water is pushed out of the soil column (``l_holdwater = FALSE``) instead of into an adjacent layer (``l_holdwater = TRUE``). + + TRUE + Supersaturated soil moisture from implicit calculation goes into an adjacent layer + (above or below depending on :nml:mem:`l_soil_sat_down`). This option was added in JULES 5.1. + + FALSE + Supersaturated soil moisture from implicit calculation goes out of the base of the soil column. + + +.. nml:member:: soilhc_method + + :type: integer + :permitted: 1, 2 or 3 + :default: 1 + + Switch for soil thermal conductivity model. + + 1. | Use approach of Cox et al (1999), as in JULES2.0. + | This is likely to predict values of soil thermal conductivity that are too low (Dharssi et al, 2009). + + 2. | Use approach of Dharssi et al (2009), which was adapted from Johansen (1975) and described by Peters-Lidard et al. (1998). + | This is not recommended for organic soils. + + 3. | Use approach of Chadburn et al (2015). + | This is recommended when using organic soils, which can have a much lower saturated thermal conductivity than mineral soils. + + .. seealso:: + References: + + * Chadburn et al (2015). An improved representation of physical permafrost dynamics in a global land-surface scheme. Geoscientific Model Development + * Dharssi et al (2009). New soil physical properties implemented in the Unified Model at PS18. Met Office Technical note 528 + * Johansen (1975). Thermal conductivity of soils. PhD thesis. University of Trondheim, Norway + * Peters-Lidard et al (1998). The effect of soil thermal conductivity parameterisation on surface energy fluxes and temperatures. J. Atmos. Sci. 55:1209-1224 + + +.. nml:member:: l_bedrock + + :type: logical + :default: F + + Switch for using a thermal bedrock column beneath the soil column. The bedrock has no hydrological processes - diffusion of heat is the only process represented. + + Properties of the bedrock can be set using :nml:mem:`ns_deep`, :nml:mem:`hcapdeep`, :nml:mem:`hcondeep` and :nml:mem:`dzdeep`. + + TRUE + An additional bedrock column is used below the soil column. + + FALSE + No effect. + + .. seealso:: + For full details see Chadburn et al. (2015) + + +.. nml:group:: Bedrock parameters (only used if :nml:mem:`l_bedrock` = TRUE) + + .. nml:member:: ns_deep + + :type: integer + :permitted: >= 1 + :default: 100 + + The number of levels in the thermal-only bedrock. + + + .. nml:member:: hcapdeep + + :type: real + :default: 2100000.0 + + The heat capacity of the bedrock (J K\ :sup:`-1` m\ :sup:`-3` ). + + + .. nml:member:: hcondeep + + :type: real + :default: 8.6 + + The heat conductivity of the bedrock (W m\ :sup:`-2` K\ :sup:`-1` ). + + + .. nml:member:: dzdeep + + :type: real + :default: 0.5 + + The thickness of the bedrock layers (m). + + +.. nml:member:: cs_min + + :type: real + :default: 1.0e-6 + + Minimum allowed soil carbon (kg m\ :sup:`-2`). + + +.. nml:member:: zsmc + + :type: real + :permitted: > 0 + :default: 1.0 + + If a depth-averaged soil moisture diagnostic is requested, the average is calculated from the surface to this depth (m). + + +.. nml:member:: zst + + :type: real + :permitted: > 0 + :default: 1.0 + + The depth (0.0->zst) to which the soil temperature is averaged for use in the calculation of wetland methane emissions (m). + + +.. nml:member:: confrac + + :type: real + :permitted: 0 <= confrac <= 1 + :default: 0.3 + + The fraction of the gridbox assumed to be covered by convective precipitation. + + +.. nml:member:: dzsoil_io + + :type: real(sm_levels) + :default: None + + The soil layer depths (m), starting with the uppermost layer. + + Note that the soil layer depths (and hence the total soil depth) are constant across the domain. + + It is recommended that JULES uses layer depths of 0.1, 0.25, 0.65 and 2.0m, giving a total depth of 3.0m, unless there is good reason not to. + +.. nml:member:: dzsoil_elev + + :type: real + :default: None + + Depth of the tiled solid-ice bedrock-type layer used underneath individual ice tiles if :nml:mem:`JULES_SURFACE::l_elev_land_ice` is TRUE. + Effectively this sets the amount of thermal buffering each surface tile has to heat fluxes penetrating through the snowpack. + +.. nml:member:: l_tile_soil + + :type: logical + :default: False + + Switch to set the number of soil tiles to equal the number of surface tiles. Each soil tile has independent properties. + + See also :nml:mem:`l_broadcast_ancils` and :nml:mem:`JULES_INITIAL::l_broadcast_soilt`. + + .. note:: + Setting :nml:mem:`l_tile_soil` = TRUE means a separate soil tile exists for each surface tile (rather than all surface tiles using the same, single soil tile). This also alters the names of many of the soil prognostic and ancillary variables that are used (see elsewhere), with the suffix "_soilt'' being added to indicate the presence of soil tiling. The switches :nml:mem:`l_broadcast_ancils` and :nml:mem:`JULES_INITIAL::l_broadcast_soilt` allow soil tiling to be used with input files that do not contain soil tile information. Setting :nml:mem:`l_broadcast_ancils` = TRUE means that a soil ancillary file that does not contain soil tiles can be used in a tiled run. Setting :nml:mem:`JULES_INITIAL::l_broadcast_soilt` = TRUE means an initital state file that does not contain soil tiles can be used to initialise a run with soil tiles. + +.. nml:member:: l_broadcast_ancils + + :type: logical + :default: False + + Switch to allow non-soil tiled ancillary files to be broadcast to all soil tiles. Only active when :nml:mem:`l_tile_soil` is True. When reading ancillaries from the dump file, use :nml:mem:`JULES_INITIAL::l_broadcast_soilt` instead. + +.. rubric:: Footnotes + +.. [#] In the JULES2.0 User Manual this was described as the 'Clapp and Hornberger' model and the JULES code still refers to 'Clapp and Hornberger' rather than 'Brooks and Corey'. In fact there are important differences between these two hydraulic models (Marthews et al. 2014,GMD). There has been confusion in the literature and in past documentation of MOSES/JULES, but JULES uses the Brooks and Corey model when :nml:mem:`JULES_SOIL::l_vg_soil` = FALSE . + + References: + * Brooks RH & Corey AT (1964). Hydraulic properties of porous media. Colorado State University Hydrology Papers 3. + * Clapp RB & Hornberger GM (1978). Empirical Equations for Some Soil Hydraulic Properties. Water Resources Research 14:601-604. diff --git a/doc/source/namelists/jules_soil_biogeochem.nml.rst b/doc/source/namelists/jules_soil_biogeochem.nml.rst new file mode 100644 index 00000000..a138b998 --- /dev/null +++ b/doc/source/namelists/jules_soil_biogeochem.nml.rst @@ -0,0 +1,443 @@ +``jules_soil_biogeochem.nml`` +============================= + + +This file sets options and parameters for soil biogeochemistry. + +If using the single-pool or 4-pool soil models, all soil parameters are read from this file. + +If using the ECOSSE soil model, most soil parameters are read from a separate file (:ref:`jules-soil-ecosse-namelist`). + + + +``JULES_SOIL_BIOGEOCHEM`` namelist members +------------------------------------------ + +.. nml:namelist:: JULES_SOIL_BIOGEOCHEM + + +.. nml:member:: soil_bgc_model + + :type: integer + :permitted: 1, 2 or 3 + :default: 1 + + Choice for model of soil biogeochemistry. + + Possible values are: + + 1. | A single-pool model of soil carbon turnover in which the pool is not prognostic (not updated). + | This must be used when the TRIFFID vegetation model is not selected (:nml:mem:`JULES_VEGETATION::l_triffid` = FALSE). + + 2. | A 4-pool model of soil organic carbon and nitrogen, originally based on the Jenkinson (1990) model, with a single pool of inorganic N. + | Historically this was bundled with the TRIFFID vegetation model. + | This can only be used if the TRIFFID vegetation model is selected (:nml:mem:`JULES_VEGETATION::l_triffid` = TRUE). + + 3. | A 4-pool model of soil organic carbon and nitrogen, and 2 inorganic N pools (ammonium and nitrate), based on the ECOSSE model (Smith et al., 2010). + | This can only be used if the TRIFFID vegetation model is selected (:nml:mem:`JULES_VEGETATION::l_triffid` = TRUE). + | This can also be run without nitrogen (:nml:mem:`JULES_SOIL_ECOSSE::l_soil_n` = FALSE). + + .. warning:: + The ECOSSE model in JULES is still in development and is not fully functional in this version. The code is included to allow further development. Users should not try to use ECOSSE. + + .. seealso:: + References: + + * Jenkinson, D.S., 1990. The turnover of organic carbon and nitrogen in soil. Philosophical Transactions of the Royal Society of London. Series B: Biological Sciences, 329(1255), pp.361-368. (https://doi.org/10.1098/rstb.1990.0177) + + * Smith et al., 2010, Estimating changes in Scottish soil carbon stocks using ECOSSE. I. Model description and uncertainties, Climate Research, 45: 179-192. (https://doi.org/10.3354/cr00899). + + +.. nml:group:: Parameters that can be used with all soil models + + .. nml:member:: q10_soil + + :type: real + :default: 2.0 + + Q10 factor for soil respiration. + + With the single-pool or 4-pool models this is only used if :nml:mem:`l_q10` = TRUE. + + With the ECOSSE model this is only used if :nml:mem:`JULES_SOIL_ECOSSE::temp_modifier` = 1. + + See Hadley Centre Technical Note 24, Eq.17, available from `the Met Office Library `_. + + +.. nml:group:: Parameters for the single-pool model (only used if :nml:mem:`soil_bgc_model` = 1) + + .. nml:member:: kaps + + :type: real + :default: 0.5e-8 + + Specific soil respiration rate at 25 degC and optimum soil moisture (s\ :sup:`-1`). + + See Hadley Centre Technical Note 24, Eq.16, available from `the Met Office Library `_. + + +.. nml:group:: Parameters for the single-pool and 4-pool models (only used if :nml:mem:`soil_bgc_model` = 1 or 2) + + .. nml:member:: l_q10 + + :type: logical + :default: T + + Switch for use of Q10 approach when calculating soil respiration. + + TRUE + Use Q10 approach (Equation 65 in Clark et al., 2011). + + .. note:: This is always enforced if the single-pool model is selected (:nml:mem:`soil_bgc_model` = 1) and was used in JULES2.0. + + FALSE + Use the approach of Jenkinson (1990) (Equation 66 in Clark et al., 2011). + + .. seealso:: + References: + + * Jenkinson, D.S., 1990. The turnover of organic carbon and nitrogen in soil. Philosophical Transactions of the Royal Society of London. Series B: Biological Sciences, 329(1255), pp.361-368. (https://doi.org/10.1098/rstb.1990.0177) + + * Clark, D. B., Mercado, L. M., Sitch, S., Jones, C. D., Gedney, N., Best, M. J., Pryor, M., Rooney, G. G., Essery, R. L. H., Blyth, E., Boucher, O., Harding, R. J., Huntingford, C., and Cox, P. M.: The Joint UK Land Environment Simulator (JULES), model description – Part 2: Carbon fluxes and vegetation dynamics, Geosci. Model Dev., 4, 701–722, (https://doi.org/10.5194/gmd-4-701-2011), 2011. + + .. nml:member:: l_soil_resp_lev2 + + :type: logical + :default: F + + Switch affecting the temperature and moisture used for soil respiration calculation. + + TRUE + Temperature and total (frozen+unfrozen) moisture content of the second soil layer are used. + + FALSE + Temperature and unfrozen moisture content of the first (topmost) soil layer are used. + + .. note:: If layered soil C is used (:nml:mem:`l_layeredc` = TRUE) the temperature and moisture of each soil layer is used to calculation respiration from that layer. + + + +.. nml:group:: Parameters for the 4-pool model (only used if :nml:mem:`soil_bgc_model` = 2) + + .. nml:member:: l_layeredc + + :type: logical + :default: F + + Switch for using the layered soil carbon model. + + If the 4-pool model is used (:nml:mem:`soil_bgc_model` = 2) this uses the approach of Burke et al. (2017) and two extra parameters are required: :nml:mem:`tau_resp`, :nml:mem:`tau_lit`. + + Layered soil nitrogen is also available if the nitrogen cycle is switched on (:nml:mem:`JULES_VEGETATION::l_nitrogen` = TRUE), but this is a highly experimental version which needs further evaluation and so should be used with extreme caution. One additional parameter is required for layered soil nitrogen: :nml:mem:`diff_n_pft`. + + TRUE + The number and thickness of layers in the soil carbon model are set equal to those in the soil moisture model (:nml:lst:`JULES_SOIL`). + + FALSE + There are no specific layers in the soil carbon model (a single, bulk pool). + + .. seealso:: + References: + + * Burke, E. J., Chadburn, S. E., and Ekici, A.: A vertical representation of soil carbon in the JULES land surface scheme (vn4.3_permafrost) with a focus on permafrost regions, Geosci. Model Dev., 10, 959-975, doi:10.5194/gmd-10-959-2017, 2017. + + .. nml:member:: l_label_frac_cs + + :type: logical + :default: F + + Switch for labelling and tracing a subset of the layered soil carbon (:nml:mem:`l_layeredc` = TRUE). It uses the approach of Burke et al.(2017). This requires the 4-pool model to be used (:nml:mem:`soil_bgc_model` = 2). The fraction of labelled soil carbon needs to be specified as part of the model's initial state. + + TRUE + A user-defined fraction of soil carbon is labelled. + + FALSE + None of the soil carbon is labelled. + + .. seealso:: + References: + + * Burke, E. J., Chadburn, S. E., and Ekici, A.: A vertical representation of soil carbon in the JULES land surface scheme (vn4.3_permafrost) with a focus on permafrost regions, Geosci. Model Dev., 10, 959-975, doi:10.5194/gmd-10-959-2017, 2017. + + .. nml:member:: kaps_4pool + + :type: real(4) + :default: 3.22e-7, 9.65e-9, 2.12e-8, 6.43e-10 + + Specific soil respiration rate for the 4-pool submodel for each soil carbon pool (decomposable plant material, resistant plant material, biomass, humus). + + + .. nml:member:: bio_hum_cn + + :type: real + :default: 10.0 + + Parameter controlling ratio of C to N for BIO and HUM pools. + + + .. nml:member:: sorp + + :type: real + :default: 10.0 + + Parameter controlling the leaching of inorganic N through the soil profile. A factor of 1 means that in a timestep all the inorganic N is available for leaching. The default value of 10 means that 10% of inorganic N is available for leaching. + + + .. nml:member:: n_inorg_turnover + + :type: real + :default: 1.0 + + Parameter controlling the lifetime of the inorganic N pool. A value of 1 implies the whole pool will turnover in 360 days. + + + .. nml:member:: tau_resp + + :type: real + :default: 2.0 + + Parameter controlling decay of respiration with depth (m-1). Only used with layered soil carbon (:nml:mem:`l_layeredc` = TRUE). + + + .. nml:member:: diff_n_pft + + :type: real + :default: 5.0 + + 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 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): + + .. nml:member:: tau_lit + + :type: real + :default: 5.0 + + Parameter controlling the decay of litter with depth (m-1). + With 4-pool, this is only used with layered soil carbon (:nml:mem:`l_layeredc` = TRUE). + With ECOSSE, this is only used with :nml:mem:`JULES_SOIL_ECOSSE::plant_input_profile` = 2. + +.. nml:group:: Methane parameters and switches. Can only be used with the single-pool and 4-pool models (:nml:mem:`soil_bgc_model` = 1 or 2). + + .. warning:: + Some parameters may need to be re-tuned for different soil biogeochemistry models. + + .. nml:member:: l_ch4_tlayered + + :type: logical + :default: F + + Switch to calculate methane emissions based on layered soil temperature. + + TRUE + Methane emission is calculated from layered soil temperatures. + + FALSE + Methane emission is calculated from top 1m average soil temperature (default). + + .. nml:member:: l_ch4_interactive + + :type: logical + :default: F + + Switch to couple the methane emission into the carbon cycle. In order to use this the methane must be calculated from layered soil temperature (:nml:mem:`l_ch4_tlayered` = TRUE). + + TRUE + Methane flux is subtracted from soil carbon stocks. + + FALSE + Methane emission is only diagnostic (default). + + .. nml:member:: l_ch4_microbe + + :type: logical + :default: F + + Switch to enable the microbial methane production scheme (represents the dynamics of methanogens and a dissolved substrate pool). See Chadburn et al. (2020). + + .. note:: This will only be applied to the methane production from your chosen :nml:mem:`ch4_substrate`. The scheme has been calibrated with :nml:mem:`ch4_substrate` = 1. + + TRUE + Microbial dynamics simulated in methane scheme. + + FALSE + No microbial dynamics, decomposition of substrate translates immediately to methane emissions. + + .. nml:member:: ch4_substrate + + :type: integer + :permitted: 1, 2 or 3 + :default: 1 + + Choice of substrate for wetland methane. This controls the calculation method for the methane flux that is used to update soil carbon (only if :nml:mem:`l_ch4_interactive` = TRUE) and to populate the variable fch4_wetl (seen by the atmospheric model in coupled mode). + + Possible values are: + + 1. | Using soil carbon as substrate (default). + 2. | Using NPP as substrate. + 3. | Using soil respiration as substrate. + + This replaces the previous switch l_wetland_ch4_npp. + + .. nml:member:: t0_ch4 + + :type: real + :default: 273.15 + + Reference temperature for the Q10 function CH4 emission calculation + + .. nml:member:: const_ch4_cs + + :type: real + :default: 7.41e-12 + + Scale factor for wetland CH4 emissions when soil carbon is taken as the substrate for ch4 emissions (:nml:mem:`ch4_substrate` = 1) + + .. note:: In the UM the recommended value depends on :nml:mem:`JULES_VEGETATION::l_triffid` as follows: + + | :nml:mem:`JULES_VEGETATION::l_triffid` = FALSE, :nml:mem:`const_ch4_cs` = 5.41e-12 + | :nml:mem:`JULES_VEGETATION::l_triffid` = TRUE, :nml:mem:`const_ch4_cs` = 5.41e-10 + + .. nml:member:: q10_ch4_cs + + :type: real + :default: 3.7 + + Q10 value for wetland CH4 emissions when soil carbon is taken as the substrate for ch4 emissions (:nml:mem:`ch4_substrate` = 1) + + .. nml:member:: const_ch4_npp + + :type: real + :default: 9.99e-3 + + Scale factor for wetland CH4 emissions when NPP is taken as the substrate for ch4 emissions (:nml:mem:`ch4_substrate` = 2) + + .. nml:member:: q10_ch4_npp + + :type: real + :default: 1.5 + + Q10 value for wetland CH4 emissions when npp is taken as the substrate for ch4 emissions (:nml:mem:`ch4_substrate` = 2) + + .. nml:member:: const_ch4_resps + + :type: real + :default: 4.36e-3 + + Scale factor for wetland CH4 emissions when soil respiration is taken as the substrate for ch4 emissions (:nml:mem:`ch4_substrate` = 3) + + .. nml:member:: q10_ch4_resps + + :type: real + :default: 1.5 + + Q10 value for wetland CH4 emissions when soil respiration is taken as the substrate for ch4 emissions (:nml:mem:`ch4_substrate` = 3) + + .. nml:member:: ch4_cpow + + :type: real + :default: 1.0 + + Power of soil carbon used to calculate methane emissions with soil carbon as substrate (:nml:mem:`ch4_substrate` = 1). Methane production is calculated as cs\ :sup:`ch4_cpow`. A value of 1.0 is default, but a value of 2/3 is consistent with an assumption that only the surfaces of the organic matter are accessible. + + .. note:: :nml:mem:`const_ch4_cs` will need retuning if this parameter is changed. + +.. nml:group:: Methane parameters only used with layered soil temperatures (:nml:mem:`l_ch4_tlayered` = TRUE). + + .. nml:member:: tau_ch4 + + :type: real + :default: 6.5 + + Exponent in the exponential decline of methane emissions with soil depth (m-1). + This empirically represents methane oxidation/emission processes, which only allow a fraction of the methane produced in the soil to reach the atmosphere. + +.. nml:group:: Methane parameters only used with microbial methane scheme (:nml:mem:`l_ch4_microbe` = TRUE). + + .. nml:member:: k2_ch4 + + :type: real + :default: 0.01 + + Baseline methanogenic respiration rate (hr-1). + + .. nml:member:: kd_ch4 + + :type: real + :default: 0.0003 + + Baseline methanogenic mortality rate (hr-1). + + .. nml:member:: rho_ch4 + + :type: real + :default: 47.0 + + Factor in substrate limitation function (related to half saturation of substrate for methanogenic respiration) ( (mgC/m3)-1 ). + + .. nml:member:: q10_mic_ch4 + + :type: real + :default: 4.3 + + Q10 factor for methanogens. + + .. nml:member:: cue_ch4 + + :type: real + :default: 0.03 + + Carbon use efficiency of methanogenic growth. + + .. nml:member:: mu_ch4 + + :type: real + :default: 0.00042 + + Threshold growth rate below which methanogens die (hr-1). + + .. nml:member:: frz_ch4 + + :type: real + :default: 0.5 + + Factor to reduce CH4 substrate production when soil is sufficiently frozen (only in microbial scheme). + + .. nml:member:: alpha_ch4 + + :type: real + :default: 0.001 + + Ratio between maintenance and growth respiration rates for methanogens. + + .. nml:member:: ev_ch4 + + :type: real + :default: 5.0 + + Timescale over which methanogenic traits adapt to temperature change (yr) + + .. nml:member:: q10_ev_ch4 + + :type: real + :default: 2.2 + + Q10 for temperature response of methanogenic traits under adaptation + +.. seealso:: + Reference for microbial methane scheme: + + * Chadburn, S. E. et al (2020), + Modeled Microbial Dynamics Explain the Apparent Temperature Sensitivity + of Wetland Methane Emissions. Global Biogeochemical Cycles, 34: + e2020GB006678. `https://doi.org/10.1029/2020GB006678 + `_ diff --git a/doc/source/namelists/jules_soil_ecosse.nml.rst b/doc/source/namelists/jules_soil_ecosse.nml.rst new file mode 100644 index 00000000..96e77bdb --- /dev/null +++ b/doc/source/namelists/jules_soil_ecosse.nml.rst @@ -0,0 +1,409 @@ + +.. _jules-soil-ecosse-namelist: + +``jules_soil_ecosse.nml`` +============================= + + +This file sets options and parameters for the ECOSSE model of soil biogeochemistry. It is used only if the ECOSSE model is chosen (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 3). + +.. warning:: + The ECOSSE model in JULES is still in development and is not fully functional in this version. The code is included to allow further development. Users should not try to use ECOSSE. + +.. seealso:: + References: + + * Smith et al., 2010, Estimating changes in Scottish soil carbon stocks using ECOSSE. I. Model description and uncertainties, Climate Research, 45: 179-192. (https://doi.org/10.3354/cr00899). + + * Clark, D. B., Mercado, L. M., Sitch, S., Jones, C. D., Gedney, N., Best, M. J., Pryor, M., Rooney, G. G., Essery, R. L. H., Blyth, E., Boucher, O., Harding, R. J., Huntingford, C., and Cox, P. M.: The Joint UK Land Environment Simulator (JULES), model description – Part 2: Carbon fluxes and vegetation dynamics, Geosci. Model Dev., 4, 701–722, (https://doi.org/10.5194/gmd-4-701-2011), 2011. + + +``JULES_SOIL_ECOSSE`` namelist members +------------------------------------------ + +.. nml:namelist:: JULES_SOIL_ECOSSE + + +.. nml:member:: l_soil_n + + :type: logical + :default: T + + Switch to include soil nitrogen in ECOSSE. + + TRUE + Model soil carbon and nitrogen. + + FALSE + Model only soil carbon. + + +.. nml:member:: l_match_layers + + :type: logical + :default: T + + Switch to match ECOSSE soil C and N layers to those for soil moisture. + + TRUE + Use the same layering as for soil moisture. The number of soil carbon layers will equal :nml:mem:`JULES_SOIL::sm_levels`, with layer thicknesses given by :nml:mem:`JULES_SOIL::dzsoil_io`. + + FALSE + The number of layers will be specified by :nml:mem:`dim_cslayer` and the thicknesses by :nml:mem:`dz_soilc_io`. + + +.. nml:member:: dim_cslayer + + :type: integer + :permitted: >= 1 + :default: None + + The number of ECOSSE soil carbon layers. Not used if :nml:mem:`l_match_layers` = TRUE. Despite the similar name, this parameter is unrelated to :nml:mem:`JULES_INPUT_GRID::sclayer_dim_name`. + + +.. nml:member:: dz_soilc_io + + :type: real(dim_cslayer) + :permitted: > 0 + :default: None + + Thicknesses of the ECOSSE soil carbon layers (m). Not used if :nml:mem:`l_match_layers` = TRUE. In most cases the total depth must equal that of the soil moisture layers (see :nml:mem:`JULES_SOIL::dzsoil_io`). The exception is the case of a single layer, bulk model (:nml:mem:`dim_cslayer` = 1), for which dz_soilc(1) is interpreted as the representative or averaging depth for the bulk layer (e.g. the temperature of the bulk model is taken as the average over this depth). + + +.. nml:member:: dt_soilc + + :type: REAL + :permitted: >= :nml:mem:`JULES_TIME::timestep_len` + :default: :nml:mem:`JULES_TIME::timestep_len` + + The timestep length for ECOSSE (seconds). The main JULES timestep length :nml:mem:`JULES_TIME::timestep_len` must be a multiple of this timestep length, so that ECOSSE is called on JULES timesteps. The TRIFFID timestep length :nml:mem:`JULES_VEGETATION::triffid_period` (converted to seconds) must also be a multiple of the ECOSSE timestep length. + + +.. nml:member:: l_driver_ave + + :type: logical + :default: T + + Switch controlling the averaging of the physical driving variables that are input to ECOSSE (e.g. soil temperature). + + TRUE + Average the driving variables over the ECOSSE timestep length. + + FALSE + Use instantaneous values of the driving variables at the time when ECOSSE is called. + + +.. nml:member:: plant_input_profile + + :type: INTEGER + :permitted: 1 or 2 + :default: 1 + + Switch for the vertical distribution of litterfall inputs of C and N to the soil. + + Possible values are: + + 1. | Fraction :nml:mem:`pi_sfc_frac` of inputs are distributed uniformly in a surface layer of depth :nml:mem:`pi_sfc_depth`, the remainder are distributed according to the distribution of roots. + + 2. | Inputs decrease exponentially with depth with decay constant :nml:mem:`JULES_SOIL_BIOGEOCHEM::tau_lit`. + + +.. nml:member:: pi_sfc_frac + + :type: REAL + :default: 0.3 + + Fraction of plant litterfall that is added to the surface soil layer of depth :nml:mem:`pi_sfc_depth`. Only used if :nml:mem:`plant_input_profile` = 1. + + +.. nml:member:: pi_sfc_depth + + :type: REAL + :default: 0.1 + + Depth of soil over which fraction :nml:mem:`pi_sfc_frac` of plant litterfall is added (m). Only used if :nml:mem:`plant_input_profile` = 1. + + +.. nml:member:: temp_modifier + + :type: INTEGER + :permitted: 1 or 2 + :default: 2 + + Switch for the form of the temperature rate modifier for decomposition. + + 1. | Use a Q10 approach (Eqn. 65 of Clark et al. (2011)) + + 2. | Use the Smith et al. (2010) form of the modifier (Eqn.1 of Smith et al. (2010)) + + +.. nml:member:: water_modifier + + :type: INTEGER + :permitted: 1 or 2 + :default: 2 + + Switch for the form of the water rate modifier for decomposition and nitrification. + + 1. | Use the Clark et al. (2011) form of the modifier (Eqn. 67 of Clark et al. (2011)). Note however that only the unfrozen water is considered here. + + 2. | Use the Smith et al. (2010) form of the modifier. + + +.. nml:member:: decomp_rate + + :type: REAL(4) + :default: 3.22e-7, 9.65e-9, 2.12e-8, 6.43e-10 + + Rate constant for decomposition of each soil carbon pool (s\ :sup:`-1`). + + Note that these default values are also those for use with the 4-pool model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::kaps_4pool`). + + +.. nml:member:: decomp_ph_rate_min + + :type: REAL + :default: 0.2 + + Minimum allowed value of pH rate modifier for decomposition. + + +.. nml:member:: decomp_ph_min + + :type: REAL + :permitted: decomp_ph_min <= decomp_ph_max + :default: 1.0 + + Soil pH below which rate of decomposition is minimum. + + +.. nml:member:: decomp_ph_max + + :type: REAL + :permitted: decomp_ph_max >= decomp_ph_min + :default: 4.5 + + Soil pH above which rate of decomposition is maximum. + + +.. nml:member:: decomp_temp_coeff_smith + + :type: REAL(3) + :default: 47.9, 106.0, 18.3 + + Constants in the 4-pool from of the decomposition temperature modifier (:nml:mem:`temp_modifier` = 2). + + Note that these default values are also those harwired in the code for use with the 4-pool model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2, :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_q10` = F ). + + + +.. nml:member:: decomp_wrate_min_smith + + :type: REAL + :default: 0.2 + + Minimum allowed value of the water rate modifier for decomposition when the 4-pool form is used (:nml:mem:`water_modifier` = 2). + + +.. nml:member:: decomp_wrate_min_clark + + :type: REAL + :default: 0.2 + + Minimum allowed value of the water rate modifier for decomposition when the Clark et al. (2011) form is used (:nml:mem:`water_modifier` = 1). + + Note that this default value is also that harwired in the code for use with the 4-pool model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2). + + +.. nml:group:: Parameters for ECOSSE that are only used if soil N is included (:nml:mem:`l_soil_n` = TRUE). + + + .. nml:member:: l_decomp_slow + + :type: logical + :default: T + + Switch controlling how lack of nitrogen affects soil decomposition. + + TRUE + Reduce the decomposition rate. + + FALSE + Reduce the efficiency of decomposition, so that decomposition results in increased production of CO\ :sub:`2` and decreased production of further soil C. This is the approach used in the standalone version of ECOSSE. + + + .. nml:member:: depo_nit_frac + + :type: REAL + :permitted: 0 <= depo_nit_frac <= 1 + :default: 1.0 + + The fraction of nitrogen deposition that is aded to the soil nitrate pool. The complement is aded to the ammonium pool. + + + .. nml:member:: bacteria_min_frac + + :type: REAL + :permitted: 0 <= bacteria_min_frac <= 1 + :default: 0.2 + + The minimum fraction of the decomposer community that are bacteria. + + + .. nml:member:: bacteria_max_frac + + :type: REAL + :permitted: bacteria_min_frac <= bacteria_max_frac <= 1 + :default: 0.5 + + The maximum fraction of the decomposer community that are bacteria. + + + .. nml:member:: bacteria_min_frac_pH + + :type: REAL + :default: 4.0 + + The soil pH at or below which the fraction of bacteria is at a minimum. + + + .. nml:member:: bacteria_max_frac_pH + + :type: REAL + :permitted: bacteria_min_frac_pH <= bacteria_max_frac_pH + :default: 5.5 + + The soil pH at or above which the fraction of bacteria is at a maximum. + + + .. nml:member:: cn_bacteria + + :type: REAL + :default: 5.5 + + The C:N ratio of soil bacteria. + + + .. nml:member:: cn_fungi + + :type: REAL + :default: 5.5 + + The C:N ratio of soil fungi. + + + .. nml:member:: depth_nitrif + + :type: REAL + :default: 0.25 + + Greatest depth at which nitrification and denitrification are allowed (m). + + + .. nml:member:: nitrif_rate + + :type: REAL + :default: 9.921e-7 + + Rate constant for nitrification (s\ :sup:`-1`). + + + .. nml:member:: nitrif_wrate_min + + :type: REAL + :default: 0.6 + + Minimum allowed value of the water rate modifier for nitrification when 4-pool form is used. Only used if :nml:mem:`water_modifier` = 2.). + + + .. nml:member:: nitrif_max_factor + + :type: REAL + :default: 0.1 + + Shape factor in rate modifier for nitrification (kg m\ :sup:`-3`). + + + .. nml:member:: nitrif_frac_n2o_fc + + :type: REAL + :permitted: 0 <= nitrif_frac_n2o_fc <= 1 + :default: 0.02 + + Fraction of nitrification lost as N\ :sub:`2`\ O by partial nitrification at field capacity. + + + .. nml:member:: nitrif_frac_gas + + :type: REAL + :permitted: 0 <= nitrif_frac_gas <= 1 + :default: 0.02 + + Fraction of nitrification lost as gas through full nitrification. + + + + .. nml:member:: nitrif_frac_no + + :type: REAL + :permitted: 0 <= nitrif_frac_no <= 1 + :default: 0.4 + + Fraction of nitrification gas loss through full nitrification that is NO. + + + .. nml:member:: denit50 + + :type: REAL + :default: 0.033 + + Amount of nitrate at which denitrification rate is 50% of the potential rate (kg m\ :sup:`-3`). + + + .. nml:member:: denit_bio_factor + + :type: REAL + :default: 0.005 + + Factor in denitrification calculation to convert flux of CO\ :sub:`2` into a representation of biological activity (m\ :sup:`2` kg\ :sup:`-1`). + + + .. nml:member:: denit_frac_n2_fc + + :type: REAL + :permitted: 0 <= denit_frac_n2_fc <= 1 + :default: 0.55 + + Proportion of denitrified N that becomes N\ :sub:`2` when soil moisture is at field capacity. + + + .. nml:member:: denit_nitrate_equal + + :type: REAL + :default: 0.4 + + Amount of N in soil nitrate at which denitrified N is released as equal amounts of N\ :sub:`2` and N\ :sub:`2`O (kg m\ :sup:`-3`). + + + .. nml:member:: denit_water_coeff + + :type: REAL(3) + :default: 0.62, 0.38, 1.74 + + Constants describing water modifier for denitrification. + + + .. nml:member:: amm_leach_min + + :type: REAL + :default: 0.02 + + Minimum allowed amount of N in soil ammonium after leaching (kg m\ :sup:`-3`). + + + .. nml:member:: n_inorg_max_conc + + :type: REAL + :default: -1.0 + + Maximum-allowed concentration of inorganic N in a layer (kg m\ :sup:`-3`). A value less than zero means no maximum concentration is imposed. diff --git a/doc/source/namelists/jules_surface.nml.rst b/doc/source/namelists/jules_surface.nml.rst new file mode 100644 index 00000000..bb795534 --- /dev/null +++ b/doc/source/namelists/jules_surface.nml.rst @@ -0,0 +1,309 @@ +``jules_surface.nml`` +===================== + + +This file sets the surface options. It contains one namelist called :nml:lst:`JULES_SURFACE`. + + + +``JULES_SURFACE`` namelist members +---------------------------------- + +.. nml:namelist:: JULES_SURFACE + +.. nml:member:: all_tiles + + :type: integer + :permitted: 0,1 + :default: 0 + + Perform calculations of tile properties on all tiles (except land ice) for all gridpoints even when the tile fraction is zero. + + 0. Off + 1. On + +.. nml:member:: cor_mo_iter + + :type: integer + :permitted: 1-4 + :default: 1 + + Corrections to Monin-Obukhov surface exchange calculation. Please see also `UMDP24 "The Parametrization of Boundary Layer Processes" (section 8.4.1) `_. + + 1. Correct convective gustiness in low winds + 2. Correct U* in dust scheme, + 3. Limit Obukhov length in low winds + 4. Improve the initialisation of the iteration + + .. note:: + Option 4 should be the preferred option. + +.. nml:member:: beta_cnv_bl + + :type: real + :permitted: >=0.0 + + Dimensionless coefficient scaling the boundary layer convective + gustiness contribution to surface exchange. Historically this was + set to 0.08 but is recommended to be reduced to 0.04 when gustiness + from convective downdraughts is included, either from the + convection parametrization or when convection is resolved (so + resolutions ~1km or finer). Please see also `UMDP24 "The + Parametrization of Boundary Layer Processes" (section 8.1) + `_. + +.. nml:member:: l_aggregate + + :type: logical + :default: F + + Switch controlling number of surface tiles for each gridbox. + + This is used to set the number of surface energy balances that are solved for each gridbox (``nsurft``). + + TRUE + Aggregate parameter values are used to solve a single energy balance per gridbox. This option sets ``nsurft = 1``. + + FALSE + A separate energy balance is calculated for each surface type. This option sets ``nsurft = ntype``. + + +.. nml:member:: i_aggregate_opt + + :type: integer + :permitted: 0-1 + :default: 0 + + Option for aggregating surface properties to surface tiles: + + 0. Aggregate momentum roughness lengths and set the thermal roughness length as a given fraction of this (in practice the ratio of roughness lengths for the first surface type). + 1. Aggregate the thermal roughness lengths separately from the momentum roughness lengths using an analogous algorithm. + + .. note:: + This option is ignored unless :nml:mem:`l_aggregate` is true. + + +.. nml:member:: l_epot_corr + + :type: logical + :default: F + + TRUE + Use correction to the calculation of potential evaporation. + + FALSE + No effect. + + +.. nml:member:: l_point_data + + :type: logical + :default: F + + Flag indicating if driving data are point or area-average values. This affects the treatment of precipitation input and how snow affects the albedo. + + TRUE + Driving data are point data. Precipitation is not distributed in space (see FALSE below) and is all assumed to be large-scale in origin. The albedo formulation is suitable for a point. + + FALSE + Driving data are area averages. The precipitation inputs are assumed to be exponentially distributed in space, as in UMDP25, and can include convective and large-scale components. The albedo formulation is suitable for a gridbox. + + +.. nml:member:: l_land_ice_imp + + :type: logical + :default: F + + Switch to control the use of implicit numerics to update land ice temperatures. + + TRUE + Use implicit numerics to update land ice temperatures. + + FALSE + Use explicit numerics to update land ice temperatures. + + +.. nml:member:: l_anthrop_heat_src + + :type: logical + :default: F + + Switch for inclusion of anthropogenic contribution to the surface heat flux from *urban* surface types. If :nml:mem:`JULES_SURFACE::l_urban2t` then the anthropogenic heat will be distributed between the :nml:mem:`JULES_SURFACE_TYPES::urban_canyon` and :nml:mem:`JULES_SURFACE_TYPES::urban_roof` according to :nml:mem:`JULES_URBAN::anthrop_heat_scale`, otherwise it is added to :nml:mem:`JULES_SURFACE_TYPES::urban` only. + + TRUE + Add anthropogenic effect. + + FALSE + No effect. + + +.. nml:member:: anthrop_heat_option + + :type: integer + :permitted: 0-1 + :default: 0 + + Switch for how urban anthropogenic heat is calculated. Only used if :nml:mem:`JULES_SURFACE::l_anthrop_heat_src` = TRUE. + + 0. Linear interpolation of 1995-2003 monthly averages from the Digest of UK Energy Statistics (DUKES), converted to W/m2 and adjusted to fraction dissipated in urban areas. Fixed annual cycle with no diurnal variation and no geographical dependence. + 1. Use the `Flanner (2009) `_ scheme, which applies functional diurnal and annual cycles to a baseline mean anthropogenic heat flux set by :nml:mem:`JULES_SURFACE::anthrop_heat_mean`. Magnitude of the annual cycle increases with latitude and is absent for latitudes within 33 degrees north and south of the equator. + + +.. nml:member:: anthrop_heat_mean + + :type: real + :default: 20.0 + + The baseline mean anthropogenic heat flux in W/m2 used in the `Flanner (2009) `_ scheme. Only used if :nml:mem:`JULES_SURFACE::anthrop_heat_option` = 1. + + +.. nml:member:: iscrntdiag + + :type: integer + :permitted: 0-3 (standalone: 0 or 1 only) + :default: 0 + + Switch controlling method for diagnosing screen temperature. + + 0. Use surface similarity theory (no decoupling). + 1. Use surface similarity theory but allow decoupling in very + stable conditions based on the quasi-equilibrium radiative + solution. + 2. Diagnose the screen temperature including transient effects and + radiative cooling. + 3. Diagnose the screen temperature and humidity including transient + effects and radiative cooling. The diagnosis of the screen + temperature follows option 2. This is an experimental option and + is undergoing development and additional testing. + + .. note:: + Option 0 should be the preferred option in standalone i.e. no decoupling until the decoupled options are fully tested in standalone scenarios. + + +.. nml:member:: l_elev_lw_down + + :type: logical + :default: false + + If surface tiles are set to be at an elevation offset from the gridbox mean altitude (see :nml:lst:`JULES_SURF_HGT`) this switch controls + whether downwelling longwave radiation is adjusted along with surface air temperature and relative humidity. + + If true, the downwelling longwave for each surface tile not at the gridbox mean height is adjusted by an amount + proportional to the fourth power of the adjustment that has been made to the surface air temperature. The adjustments are then + scaled such that the sum over all surface tiles conserves the gridbox mean energy in the original forcing. + + +.. nml:member:: l_elev_land_ice + + :type: logical + :default: false + + Allows multiple ice surface tiles to exist in an ice gridbox, usually with each representing a different elevation (:nml:lst:`JULES_SURF_HGT`) + band on in icesheet areas so that a sub-gridscale surface mass balance term (a strong function of altitude) can be derived for forcing + icesheet/glacier models. When enabled, ice tiles in a gridbox do not use the usual (gridbox mean) JULES soil/ice subsurface model, + but each tile has an independent single layer bedrock-type solid ice boundary condition under the snowpack. + + In addition, when selected, dense snowpacks on elevated ice gridboxes are parameterised to behave more like firn in two ways: + 1) The meltwater-holding capacity of snow layers reduces as a linear function of their density, becoming zero + above the pore-closure density of 850 kg/m^2 so as to restrict retention of melt within the snowpack. + 2) Where the top few centimetres of the pack has a density appropriate to firn/bare ice + and the grain-size physics otherwise used for snow albedo become less appropriate, + surface albedo becomes a function of density, tending towards that of bare ice as density increases + (see :nml:mem:`JULES_SNOW::rho_firn_albedo`, :nml:mem:`JULES_SNOW::amax`, :nml:mem:`JULES_SNOW::aicemax`). + + If this scheme is enabled, a depth for the bedrock layer must be provided (:nml:mem:`JULES_SOIL::dzsoil_elev`) and the new tile + numbers must be specified (:nml:lst:`JULES_SURFACE_TYPES`) as either type :nml:mem:`JULES_SURFACE_TYPES::elev_ice` (for fully glaciated areas) or :nml:mem:`JULES_SURFACE_TYPES::elev_rock` (for + non-glaciated areas where the bedrock may become exposed under a thin snow layer). The total number of non-vegetated surface tiles, and + their surface properties (:nml:lst:`JULES_NVEGPARM`, usually set to be the same as the normal ice tile) must be set accordingly, + as with any surface tile. + +.. nml:member:: l_flake_model + + :type: logical + :default: false + + Switch for using the freshwater lake model 'FLake' on the lake/inland-water surface tile. More information on the FLake model can be found on `the FLake website `_. A description of how FLake is coupled to JULES can be found in `Rooney and Jones 2010 `_. + + When using FLake, it is not necessary to use a canopy representation of lake properties so :nml:mem:`JULES_NVEGPARM::catch_nvg_io`, + :nml:mem:`JULES_NVEGPARM::ch_nvg_io` and :nml:mem:`JULES_NVEGPARM::vf_nvg_io` should all be set to zero for the lake tile. + +.. nml:member:: l_urban2t + + :type: logical + :default: false + + Switch for using the two-tile urban schemes (including MORUSES). This allows two urban surface tiles (:nml:mem:`JULES_SURFACE_TYPES::urban_canyon` and :nml:mem:`JULES_SURFACE_TYPES::urban_roof`) to be used instead of one. + Additional parameters must be supplied via :nml:lst:`JULES_NVEGPARM`, with some able to be provided by MORUSES (see :nml:lst:`JULES_URBAN`). + +.. nml:member:: l_mo_buoyancy_calc + + :type: logical + :default: false + + Default JULES (l_mo_buoyancy_flux = false) uses the buoyancy from the previous timestep to calculate the surface transfer coefficients. In coupled simulations this can lead to unrealistic surface temperatures if the stability suddenly + switches from stable to unstable, due to the low turbulence determined by the stable buoyancy flux. + + With the interactive buoyancy flux option (l_mo_buoyancy_flux = true) the surface energy balance and buoyancy flux are calculated within the iterative calculation for the Monin-Obukhov similarity theory for the surface exchange + coefficients. On occations when the stability is around neutral it is possible that the iterative calculation does not converge. In this case the larger of the last two calculated transfer coefficients is then used to prevent + any unrealistic surface temperatures. + +.. nml:group:: Surface parameters + + .. nml:member:: hleaf + + :type: real + :default: 5.7e4 + + Specific heat capacity of leaves (J K\ :sup:`-1` per kg carbon). + + See Hadley Centre Technical Note 30, p6, available from `the Met Office Library `_. + + + .. nml:member:: hwood + + :type: real + :default: 1.1e4 + + Specific heat capacity of wood (J K\ :sup:`-1` per kg carbon). + + See Hadley Centre Technical Note 30, p6, available from `the Met Office Library `_. + + + .. nml:member:: beta1 + + :type: real + :default: 0.83 + + Coupling coefficient for co-limitation in photosynthesis model. + + See Cox et al. (1999), Eq.61. + + + .. nml:member:: beta2 + + :type: real + :default: 0.93 + + Coupling coefficient for co-limitation in photosynthesis model. + + See Cox et al. (1999), Eq.61. + + + .. nml:member:: fwe_c3 + + :type: real + :default: 0.5 + + Constant in expression for limitation of photosynthesis by transport of products, for C3 plants. + + See Cox et al. (1999) Eq.60. + + + .. nml:member:: fwe_c4 + + :type: real + :default: 20000.0 + + Constant in expression for limitation of photosynthesis by transport of products, for C4 plants. + + See Cox et al. (1999) Eq.60. diff --git a/doc/source/namelists/jules_surface_types.nml.rst b/doc/source/namelists/jules_surface_types.nml.rst new file mode 100644 index 00000000..7831fc7c --- /dev/null +++ b/doc/source/namelists/jules_surface_types.nml.rst @@ -0,0 +1,326 @@ +``jules_surface_types.nml`` +=========================== +.. _top_jules_surface_types: + +This file configures the surface types used by JULES. It contains one +namelist called :nml:lst:`JULES_SURFACE_TYPES`. + +The surface type IDs, which were introduced in the UM in order to +identify the surface types present in input and output, have been made +available to standalone. The defined surface type IDs are given in the +description here in brackets (#). In order to keep the GUI from +appearing cluttered, the surface types have been added with +``compulsory=false``, unless they are attached to specific science +options allowing them to be triggered off, which would be the +preferred method. A ``compulsory=false`` surface type, can be added +and removed in the GUI window as described in the table below. To: + + ====== ================================================= + Add "Add latent variable" using the right click menu, which opens a list of defined surface types. + Remove "Remove" the variable using the cog menu. + ====== ================================================= + +.. note:: Please be aware that while the surface type IDs have been + made available and are used to check the surface type + configuration at runtime, they are not yet used by the JULES + I/O. + +``JULES_SURFACE_TYPES`` namelist members +---------------------------------------- + + +.. nml:namelist:: JULES_SURFACE_TYPES + +.. note:: + The total number of surface types to be modelled is called ``ntype``, and is given by ``ntype = npft + nnvg``. + + In the original setup, JULES models 5 vegetation types and 4 non-vegetation types (``npft = 5``, ``nnvg = 4``). However, the model domain need not contain all 9 types, e.g. the domain could consist of a single point with 100% grass. The amount of each type in the domain is normally set in :nml:lst:`JULES_FRAC`. + + If the crop model is active (i.e. ``ncpft`` > 0), then ``nnpft = npft - ncpft`` where ``nnpft`` is the number of natural PFTs. + + Vegetation surfaces must always be present first in any list of surfaces. + +.. nml:member:: npft + + :type: integer + :permitted: >= 1 + :default: -32768 + + The number of plant functional types (PFTs) to be modelled. + + +.. nml:member:: ncpft + + :type: integer + :permitted: < npft + :default: 0 + + The number of crop plant functional types to be modelled. + + +.. nml:member:: nnvg + + :type: integer + :permitted: >= 1 + :default: -32768 + + The number of non-plant surface types to be modelled. + +.. nml:group:: Non-vegetated surface types + + A negative value, when permitted, indicates that the surface type + is not in use. + + .. nml:member:: urban + + :type: integer + :permitted: -1, npft+1:ntype + :default: -32768 + + Index of the urban surface type (#6). + + Can only be used if :nml:mem:`JULES_SURFACE::l_urban2t` = FALSE. + + + .. nml:member:: lake + + :type: integer + :permitted: npft+1:ntype + :default: -32768 + + Index of the lake surface type (#7). + + + .. nml:member:: soil + + :type: integer + :permitted: npft+1:ntype + :default: -32768 + + Index of the soil surface type (#8). + + .. note:: A soil surface type must be given (although the fraction may be set to zero). + + + .. nml:member:: ice + + :type: integer + :permitted: npft+1:ntype + :default: -32768 + + Index of the ice surface type (#9). + + .. note:: In the UM the ice surface type must be specified (although the fraction may be set to zero). + + + .. nml:group:: Multiple ice tiles allowed to exist in an ice gridbox + + These surface types can only be used when multiple ice tiles are + allowed in a gridbox i.e. when + :nml:mem:`JULES_SURFACE::l_elev_land_ice` = TRUE. + + .. nml:member:: elev_ice + + :type: integer + :permitted: -1,npft+1:ntype + :default: -32768 + + Indices of the elevated ice types (#901-925). + + Must be grouped together with values ``npft < elev_ice <= + ntype`` OR ``elev_ice = -1`` to indicate they are not used + (i.e. all elevated rock instead). + + .. nml:member:: elev_rock + + :type: integer + :permitted: -1,npft+1:ntype + :default: -32768 + + Indices of the elevated non-glaciated bedrock types + (#926-950). + + Must be grouped together, with values ``npft < elev_rock <= + ntype`` OR ``elev_rock = -1`` to indicate they are not used + (i.e. all elevated ice instead). + + + .. nml:group:: Two-tile urban schemes including MORUSES + + These surface types can only be used when :nml:mem:`JULES_SURFACE::l_urban2t` = TRUE. + + .. nml:member:: urban_canyon + + :type: integer + :permitted: npft+1:ntype + :default: -32768 + + Index of the urban canyon surface type (#601). + + + .. nml:member:: urban_roof + + :type: integer + :permitted: npft+1:ntype + :default: -32768 + + Index of the urban roof surface type (#602). + + + .. note:: + + When giving urban fraction data (see :nml:lst:`JULES_FRAC`), total *urban* fraction may be given instead of the separate canyon and roof fractions by entering it under the canyon fraction. When initialising if the roof fraction is zero, the canyon fraction will be interpreted as the total *urban* fraction and be partitioned according to the canyon fraction (W/R, see :nml:lst:`URBAN_PROPERTIES`). + +.. nml:group:: Surface types with ``compulsory=false`` + + These are required to allow the surface type configuration to be + checked at runtime and for surface types to be identified in the + output headers. These are added as a latent variable. Remove the + surface type if it is not required (see explanation at the + :ref:`top` of this page). + + .. nml:member:: usr_type + + :type: integer + :permitted: 1:ntype + :default: -32768 + + Index of user specified surface type (#10-99). + + A user surface type can be used when experimenting with new + surface configurations without a code change. These can be + either vegetated or non-vegetated and are used solely to assign an + ID number. + + .. nml:group:: Vegetated surface types + + A negative value, when permitted, indicates that the surface + type is not in use. + + .. nml:member:: brd_leaf + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of the original broadleaf PFT surface type (#1). + + .. nml:member:: brd_leaf_dec + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of broadleaf (decidous) PFT surface type (#101) + + .. nml:member:: brd_leaf_eg_trop + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of broadleaf (evergreen tropical) PFT surface type (#102). + + .. nml:member:: brd_leaf_eg_temp + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of broadleaf (evergreen temperate) PFT surface type (#103). + + .. nml:member:: ndl_leaf + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of original needleleaf PFT surface type (#2). + + .. nml:member:: ndl_leaf_dec + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of needleleaf (deciduous) PFT surface type (#201). + + .. nml:member:: ndl_leaf_eg + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of needleleaf (evergreen) PFT surface type (#202). + + .. nml:member:: c3_grass + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of original C3 grass PFT surface type (#3). + + .. nml:member:: c3_crop + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of C3 crop PFT surface type (#301). + + .. nml:member:: c3_pasture + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of C3 pasture PFT surface type (#302). + + .. nml:member:: c4_grass + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of original C4 grass PFT surface type (#4). + + .. nml:member:: c4_crop + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of C4 crop PFT surface type (#401). + + .. nml:member:: c4_pasture + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of C4 pasture PFT surface type (#402). + + .. nml:member:: shrub + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of original shrub PFT surface type (#5). + + .. nml:member:: shrub_dec + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of shrub (deciduous) PFT surface type (#501). + + .. nml:member:: shrub_eg + + :type: integer + :permitted: 1:npft + :default: -32768 + + Index of shrub (evergreen) PFT surface type (#502). diff --git a/doc/source/namelists/jules_vegetation.nml.rst b/doc/source/namelists/jules_vegetation.nml.rst new file mode 100644 index 00000000..d257a40d --- /dev/null +++ b/doc/source/namelists/jules_vegetation.nml.rst @@ -0,0 +1,1052 @@ +``jules_vegetation.nml`` +======================== + + +This file sets the vegetation options. It contains one namelist called :nml:lst:`JULES_VEGETATION`. + + +``JULES_VEGETATION`` namelist members +------------------------------------- + +.. nml:namelist:: JULES_VEGETATION + +.. nml:member:: l_trait_phys + + :type: logical + :default: F + + Switch for using trait-based physiology. + + TRUE + Vcmax is calculated based on observed leaf traits. Leaf + nitrogen (nmass: kgN kgLeaf\ :sup:`-1`) and leaf mass (LMA: + kgLeaf m\ :sup:`-2`) can be based on observations from the TRY + database. Vcmax (umol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is based + on linear regressions as in :ref:`Kattge et al. 2009`. Two additional + parameters are needed: vint and vsl - the intercept and slope, + respectively, that relate the leaf nitrogen to vcmax. Sigl is + replaced with LMA (sigl=LMA*Cmass, where Cmass is the + kgC kgLeaf\ :sup:`-1` and is 0.4). + + FALSE + Vcmax is calculated based on parameters nl0 (kgN kgC\ :sup:`-1`) and neff. + + +.. nml:member:: l_phenol + + :type: logical + :default: F + + Switch for vegetation phenology model. + + TRUE + Use phenology model. + + FALSE + Do not use phenology model. + + +.. nml:member:: l_triffid + + :type: logical + :default: F + + Switch for dynamic vegetation model (TRIFFID) except for competition. + + TRUE + Use TRIFFID. In this case soil carbon is modelled using four pools + (biomass, humus, decomposable plant material, resistant plant material). + + FALSE + Do not use TRIFFID. A single soil carbon pool is used. + + +.. nml:member:: l_veg_compete + + :type: logical + :default: T + + Switch for competing vegetation. + + Only used if :nml:mem:`l_triffid` = TRUE. + + TRUE + TRIFFID will let the different PFTs compete against each other and modify the vegetation fractions. + + FALSE + Vegetation fractions do not change. + + +.. nml:member:: l_ht_compete + + :type: logical + :default: F + + Only used if :nml:mem:`l_triffid` = TRUE. + + TRUE + Use height-based vegetation competition (recommended). + + This allows for a generic number of PFTs. When + :nml:mem:`l_trif_eq` = TRUE, this is implemented by + ``lotka_eq_jls.F90``. When :nml:mem:`l_trif_eq` = FALSE, it is + implemented in ``lotka_noeq_jls.F90`` when + :nml:mem:`l_trif_crop` = FALSE and in + ``lotka_noeq_subset_jls.F90`` when :nml:mem:`l_trif_crop` = + TRUE. + + FALSE + Use the vegetation competition described in :ref:`HCTN24`. + + This is hard-wired for 5 PFTs (BT, NT, C3, C4, SH, in that + order) with co-competition for grasses and trees in + ``lokta_jls.F90``. + +.. nml:member:: l_nitrogen + + :type: logical + :default: F + + Only used if :nml:mem:`l_triffid` = TRUE. + + TRUE + Enable Nitrogen limitation of carbon uptake. A nitrogen + deposition field should be provided otherwise no N deposition is + assumed. + + FALSE + No Nitrogen limitation. Nitrogen fluxes are calculated as diagnostics only. + +.. nml:member:: l_trif_eq + + :type: logical + :default: T + + Switch for equilibrium vegetation model (i.e., an equilibrium solution of TRIFFID). + + Only used if :nml:mem:`l_triffid` = TRUE. + + TRUE + Use equilibrium TRIFFID. + + FALSE + Do not use equilibrium TRIFFID. + + +.. nml:member:: phenol_period + + :type: integer + :permitted: >= 1 + :default: None + + Period for calls to phenology model in *days*. Only relevant if :nml:mem:`l_phenol` = TRUE. + + +.. nml:member:: triffid_period + + :type: integer + :permitted: >= 1 + :default: None + + Period for calls to TRIFFID model in *days*. Only relevant if one of :nml:mem:`l_triffid` or :nml:mem:`l_trif_eq` is TRUE. + + +.. nml:member:: l_gleaf_fix + + :type: logical + :default: T + + Switch for fixing a bug in the accumulation of ``g_leaf_phen_acc``. + + This bug occurs because ``veg2`` is called on TRIFFID timesteps and + ``veg1`` is called on phenol timesteps, but ``veg1`` did not + previously accumulate ``g_leaf_phen_acc`` in the same way as + ``veg2``. + + TRUE + ``veg1`` accumulates ``g_leaf_phen_acc`` between calls to + TRIFFID. This is important if :nml:mem:`triffid_period` > + :nml:mem:`phenol_period`. + + FALSE + ``veg1`` does not accumulate ``g_leaf_phen_acc`` between calls to TRIFFID. + + +.. nml:member:: l_bvoc_emis + + :type: logical + :default: F + + Switch to enable calculation of BVOC emissions. + + TRUE + BVOC emissions diagnostics will be calculated. + + FALSE + BVOC emissions diagnostics will not be calculated. + + +.. nml:member:: l_o3_damage + + :type: logical + :default: F + + Switch for ozone damage. + + TRUE + Ozone damage is on. + + .. note:: Ozone concentration in ppb must be prescribed in :doc:`prescribed_data.nml`. + + FALSE + No effect. + +.. nml:member:: l_stem_resp_fix + + :type: logical + :default: F + + Switch for bug fix for stem respiration to use balanced LAI to + derive respiring stem mass. The switch is included for backwards + compatibility with existing configurations. Future updates should + include this change. + + TRUE + Respiring stem mass is derived allometrically. + + FALSE + Respiring stem mass varies with seasonal LAI. + + In the case of a Broadleaf tree in the winter (no leaves) this + would mean stem respiration is scaled to 0. + + +.. nml:member:: l_scale_resp_pm + + :type: logical + :default: F + + Scale whole plant maintenance respiration by the soil moisture + stress factor, instead of only scaling leaf respiration. + + TRUE + Soil moisture stress reduces leaf, root, and stem maintenance respiration. + + FALSE + Soil moisture stress only reduces leaf maintenance respiration. + + +.. nml:member:: fsmc_shape + + :type: integer + :permitted: 0,1 + :default: 0 + + Shape of soil moisture stress function on vegetation (fsmc). + + 0. Piece-wise linear in vol. soil moisture. + + 1. Piece-wise linear in soil potential. Currently only allowed when + :nml:mem:`JULES_SOIL_PROPS::const_z` = T and + :nml:mem:`JULES_VEGETATION::l_use_pft_psi` = T. + + .. note:: The option :nml:mem:`JULES_VEGETATION::fsmc_shape` = 1 is + still in development. Users should ensure that results + are as expected, and provide feedback where deficiencies + are identified. + +.. nml:member:: l_use_pft_psi + + :type: logical + :default: F + + Switch for parameters in the soil moisture stress on vegetation function (fsmc). + + TRUE + Fsmc is calculated from :nml:mem:`JULES_PFTPARM::psi_close_io` + and :nml:mem:`JULES_PFTPARM::psi_open_io`. + + FALSE + Fsmc is calculated from ``sm_wilt`` and ``sm_crit`` in + :nml:lst:`JULES_SOIL_PROPS` and + :nml:mem:`JULES_PFTPARM::fsmc_p0_io`. + + .. note:: Soil respiration and surface conductance of bare soil + respectively will depend on ``sm_wilt`` and ``sm_crit`` + in :nml:lst:`JULES_SOIL_PROPS`, regardless of the setting + of :nml:mem:`JULES_VEGETATION::fsmc_shape`. + + .. note:: The option :nml:mem:`JULES_VEGETATION::l_use_pft_psi` = T + is still in development. Users should ensure that results + are as expected, and provide feedback where deficiencies + are identified. + + +.. nml:member:: l_vegcan_soilfx + + :type: logical + :default: F + + Switch for enhancement to canopy model to allow for conduction in + the soil below the vegetative canopy, reducing coupling between the + soil and the canopy. + + TRUE + Allow for conduction in the soil. + + FALSE + No effect. + +.. nml:member:: l_leaf_n_resp_fix + + :type: logical + :default: F + + Switch for bug fix for leaf nitrogen content used in the + calculation of plant maintenance respiration. The switch is + included for backwards compatibility with existing + configurations. Runs with :nml:mem:`can_rad_mod` = 1, 4 or 5 are + affected. + + TRUE + Use correct forms for canopy-average leaf N content. + + FALSE + No effect. + +.. nml:member:: l_landuse + + :type: logical + :default: F + + Switch for using landuse change in conjunction with TRIFFID + + Only used if :nml:mem:`l_triffid` = TRUE. + + TRUE + Land use change is implemented within TRIFFID. Litter fluxes + are split between soil and wood product pools. Requires + additional prognostics covering the product pools and the + agricultural fraction from the previous TRIFFID call. + + FALSE + All litter fluxes enter the soil + + +.. nml:member:: l_recon + + :type: logical + :default: T + + Switch for reconfiguring vegetation fractions. Also initialises + vegetation and soil biogeochemistry at land ice points. With the + ECOSSE soil model this switch also ensures that the initial + condition for soil biogeochemistry is internally consistent. + + TRUE + For soil points (land points with no ice) ensure vegetation + fractions are at least a minimum value and reduce other + fractions accordingly. + + FALSE + Do not apply the minimum vegetation fractions. This is useful + when some points are 100% lake and urban, in which case + reconfiguration leads to a total surface tile fraction of greater + than 1. + + +.. nml:member:: l_prescsow + + :type: logical + :default: F + + Switch that determines how crop sowing dates are defined. Only used + if :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0. + + TRUE + Sowing dates prescribed in :nml:lst:`JULES_CROP_PROPS` are used. + + FALSE + Sowing dates are determined by the model. + + +.. nml:member:: l_trif_crop + + :type: logical + :default: F + + Switch controlling the treatment of agricultural PFTs. Where + agricultural PFTs are defined by the + :nml:mem:`JULES_TRIFFID::crop_io` parameter. + + TRUE + In the non-agricultural area natural PFT competition is + calculated by a call to a new version of the lotka routine and + in each agricultural area agricultural-PFT competition is + calculated by an additional call to the new version of the + lotka routine. Crop and pasture areas are defined by the + :nml:mem:`JULES_AGRIC::frac_agr` and + :nml:mem:`JULES_AGRIC::frac_past` variables + respectively. Additionally, to represent harvesting, a fraction + of crop litter is added to the fast wood products pool instead + of the soil carbon pools. + + FALSE + Vegetation competition is calculated for natural and crop PFTs + together, with natural PFTs excluded from the agricultural area + that is defined by the :nml:mem:`JULES_AGRIC::frac_agr` + variable. Agricultural PFTs can also grow in natural areas + where they are interpreted as natural grasses. + + +.. nml:member:: l_trif_biocrop + + :type: logical + :default: F + + Allows for representation of bioenergy crops with continuous or periodic harvesting of agricultural PFTs at prescribed intervals. Requires :nml:mem:`JULES_VEGETATION::l_trif_crop` = TRUE. + + TRUE + Crop, pasture, and bioenergy crop areas are defined by the :nml:mem:`JULES_AGRIC::frac_agr`, :nml:mem:`JULES_AGRIC::frac_past`, :nml:mem:`JULES_AGRIC::frac_biocrop` variables respectively. Harvests are permitted from any land class and enabled for each PFT separately using the :nml:mem:`JULES_TRIFFID::harvest_type_io` variable. Harvesting may be continuous (as per the existing scheme in :nml:mem:`JULES_VEGETATION::l_trif_crop`, when :nml:mem:`JULES_TRIFFID::harvest_type_io` is 1), or performed at prescribed intervals defined using the :nml:mem:`JULES_TRIFFID::harvest_freq_io` and :nml:mem:`JULES_TRIFFID::harvest_ht_io` variables (when :nml:mem:`JULES_TRIFFID::harvest_type_io` is 2). + + FALSE + Land use classes, PFT partitioning, and harvests are as defined by the :nml:mem:`JULES_VEGETATION::l_trif_crop` switch. + + .. seealso:: + References: + + * Littleton et al., 2020, JULES-BE: representation of bioenergy crops and harvesting in the Joint UK Land Environment Simulator vn5.1, Geosci. Model Dev., https://doi.org/10.5194/gmd-13-1123-2020 + + +.. nml:member:: l_ag_expand + + :type: logical + :default: F + + Allows for assisted expansion of agricultural crop areas. Requires :nml:mem:`JULES_VEGETATION::l_landuse` = TRUE. + + TRUE + Automatically plant out new crop areas with target PFTs. + + FALSE + No automatic increase of PFT fraction when land class fraction increases. + + +.. nml:member:: can_model + + :type: integer + :permitted: 1-4 + :default: 4 + + Choice of canopy model for vegetation: + + 1. No distinct canopy (i.e. surface is represented as a single entity for radiative processes). + 2. Radiative canopy with no heat capacity. + 3. Radiative canopy with heat capacity. This option is deprecated, with 4 preferred. + 4. As 3 but with a representation of snow beneath the canopy. This option is preferred to 3. + + .. note:: + :nml:mem:`can_model` = 1 does not mean that there is no + vegetation canopy. It means that the surface is + represented as a single entity, rather than having + distinct surface and canopy levels for the purposes of + radiative processes. + + +.. nml:member:: can_rad_mod + + :type: integer + :permitted: 1, 4, 5, 6 + :default: 4 + + Options for treatment of canopy radiation. + + 1. A single canopy layer for which radiation absorption is + calculated using Beer's law. Leaf-level photosynthesis is scaled + to the canopy level using the 'big leaf' approach. Leaf + nitrogen, photosynthetic capacity, i.e the Vcmax parameter, and + leaf photosynthesis vary exponentially through the canopy with + radiation. + + 4. Multi-layer approach for radiation interception following the + two-stream approach of :ref:`Sellers et + al. (1992)`. This approach takes into account leaf + angle distribution, zenith angle, and differentiates absorption + of direct and diffuse radiation. It has an exponential decline + of leaf N through the canopy and includes inhibition of leaf + respiration in the light. Canopy photosynthesis and conductance + are calculated as the sum over all layers. + + 5. This is an improvement of option 4, including: + + * Sunfleck penetration though the canopy. + * Division of sunlit and shaded leaves within each canopy level. + * A modified version of inhibition of leaf respiration in the light. + + 6. This is an improvement of option 5, including an exponential + decline of leaf N with canopy height proportional to LAI, + following Beer's law. + + .. note:: :nml:mem:`can_rad_mod` = 1 and 6 are recommended. + + .. note:: When using :nml:mem:`can_rad_mod` = 4, 5 or 6 it is + recommended to use driving data that contains direct and + diffuse radiation separately rather than a constant + diffuse fraction. + + .. seealso:: Descriptions of option 1 can be found in + :ref:`Jogireddy et al. (2006)`, and an + application of option 4 can be found in :ref:`Mercado + et al. (2007)`. Options 1 to 5 are + described in :ref:`Clark et al (2011)`. + + +.. nml:member:: ilayers + + :type: integer + :permitted: >= 0 + :default: 10 + + Number of layers for canopy radiation model. Only used for :nml:mem:`can_rad_mod` = 4, 5 or 6. + + These layers are used for the calculations of radiation interception and photosynthesis. + + +.. nml:member:: photo_model + + :type: integer + :permitted: 1 or 2 + :default: none + + Choice for model of leaf photosynthesis. + + Possible values are: + + 1. | C\ :sub:`3` and C\ :sub:`4` plants use the models of Collatz et al., 1991 and 1992, respectively. These were used in the original JULES model. + + 2. | C\ :sub:`3` plants use the model of Farquhar et al. (1980); C\ :sub:`4` plants use the model of Collatz et al. (1992). + + .. warning:: + The Farquhar model can only be used if :nml:mem:`can_rad_mod` = 1, 5 or 6. Code has not been written for other values of :nml:mem:`can_rad_mod`. + + .. seealso:: + References: + + * Collatz et al., 1991, Physiological and environmental regulation of stomatal conductance, photosynthesis, and transpiration – a model that includes a laminar boundary layer, Agricultural and Forest Meteorology, https://doi.org/10.1016/0168-1923(91)90002-8. + * Collatz et al., 1992, Coupled Photosynthesis-Stomatal Conductance Model for Leaves of C\ :sub:`4` Plants, Australian Journal of Plant Physiology, https://doi.org/10.1071/PP9920519. + * Farquhar et al., 1980, A biochemical model of photosynthetic CO\ :sub:`2` assimilation in leaves of C\ :sub:`3` species, Planta, https://doi.org/10.1007/BF0038623. + + +.. nml:member:: stomata_model + + :type: integer + :permitted: 1, 2, OR 3 + :default: 1 + + Choice for model of stomatal conductance. + + Possible values are: + + 1. The original JULES model, including the Jacobs closure - see + Eqn.9 of :ref:`Best et al. (2011)`. + + 2. The model of :ref:`Medlyn et al. (2011)` - see + 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:: + + Only the original (Jacobs) model can currently be used with the + UM (Option 1). + + +.. nml:member:: frac_min + + :type: real + :default: 1.0e-6 + + Minimum fraction that a PFT is allowed to cover if TRIFFID is used. + + +.. nml:member:: frac_seed + + :type: real + :default: 0.01 + + Seed fraction for TRIFFID. + + +.. nml:member:: pow + + :type: real + :default: 5.241e-4 + + Power in sigmodial function used to get competition coefficients. + + See Hadley Centre Technical Note 24, Eq.3. + + +.. nml:member:: l_inferno + + :type: logical + :default: F + + Switch that determines whether interactive fires (INFERNO) is + used. This allows for the diagnostic of burnt area, burnt carbon + and a variety of fire emissions. + + TRUE + INFERNO is used to provide diagnostic fire variables + + FALSE + INFERNO is not used. + +.. nml:member:: ignition_method + + :type: integer + :permitted: 1, 2, 3 + :default: 1 + + Switch to determine the type of ignition used (ubiquitous or prescribed with population and lightning) + + 1. INFERNO uses ubiquitous (constant) ignitions, of 1.67 fires km\ + :sup:`-2` s\ :sup:`-1` (1.5 from humans, 0.17 from lightning). + + 2. INFERNO uses prescribed lightning ignitions, either from an ancillary or the UM. + Meanwhile humans are assumed to ignite 1.5 fires km\ :sup:`-2` s\ :sup:`-1`. + + 3. INFERNO uses prescribed ignition using Population Density and Lightning Frequency (Cloud-to-Ground). + These must be provided as prescribed data to the JULES run. + +.. nml:member:: l_trif_fire + + :type: logical + :default: F + + Switch that determines whether interactive fire is used. This allows for burnt area to link with dynamic + vegetation. + + Only used if :nml:mem:`l_triffid` = TRUE. + + TRUE + Burnt area is calculated in INFERNO and passed to TRIFFID to + calculate vegetation dynamics. Carbon is also removed from DPM + and RPM pools in SOILCARB. + FALSE + Burnt area is zero unless prescribed via an ancillary file. + +.. nml:member:: l_vegdrag_pft + + :type: logical(npft) + :default: F + + Switch for using vegetation canopy drag scheme on each PFT. + + TRUE + Use a vegetative drag scheme. This is based on :ref:`Harman and Finnigan (2007)`. + + FALSE + Do not use vegetative drag scheme. + +.. nml:member:: l_red + + :type: logical + :default: F + + Switch to use the Robust Ecosystem Demography (RED). + This is based on :ref:`Argles, Arthur PK, et al. + (2020)`. + + Only use if any :nml:mem:`l_triffid` = TRUE. + + TRUE + Use the Robust Ecosystem Demography. + + FALSE + Do not use the Robust Ecosystem Demography. + +.. nml:member:: l_rsl_scalar + + :type: logical + :default: F + + Switch for using a roughness sublayer correction scheme in scalar + variables. This is based on :ref:`Harman and Finnigan + (2008)`. + + Only use if any :nml:mem:`l_vegdrag_pft` = TRUE. + + TRUE + Use a roughness sublayer correction scheme in scalar variables. + + FALSE + Do not use a roughness sublayer correction scheme in scalar variables. + +.. nml:member:: c1_usuh + + :type: real + :permitted: >= 0 + :default: None + + u*/U(h) at the top of dense canopy. See :ref:`Massman (1997)`. + + Only use if any :nml:mem:`l_vegdrag_pft` = TRUE. + +.. nml:member:: c2_usuh + + :type: real + :permitted: >= 0 + :default: None + + u*/U(h) at substrate under canopy. See :ref:`Massman (1997)`. + + Only use if any :nml:mem:`l_vegdrag_pft` = TRUE. + +.. nml:member:: c3_usuh + + :type: real + :permitted: >= 0 + :default: None + + This is used in the exponent of equation weighting dense and sparse + vegetation to get u*/U(h) in neutral condition. See :ref:`Massman + (1997)`. The default value is taken from :ref:`Wang + (2012)`. + + Only use if any :nml:mem:`l_vegdrag_pft` = TRUE. + +.. nml:member:: cd_leaf + + :type: real + :permitted: 0:1 + :default: None + + Leaf level drag coefficient. + + Only use if any :nml:mem:`l_vegdrag_pft` = TRUE. + +.. nml:member:: stanton_leaf + + :type: real + :permitted: 0:1 + :default: None + + Leaf-level Stanton number + + Only use if :nml:mem:`l_rsl_scalar` = TRUE. + +.. nml:member:: l_spec_veg_z0 + + :type: logical + :default: F + + Switch for using specified values of the vegetation roughness + length rather than being determined by the canopy height. + + TRUE + Vegetation roughness lengths are specified for each PFT in + :nml:mem:`JULES_PFTPARM::z0v_io`. + + FALSE + Vegetation roughness lengths are calculated using canopy + heights and parameter :nml:mem:`JULES_PFTPARM::dz0v_dh_io`. + +.. nml:member:: l_limit_canhc + + :type: logical + :default: F + + Switch for limiting the canopy heat capacity for vegetation, which + is calculated from the canopy height. + + Using the SIMARD canopy height ancillary gives very large heat + capacities in the Amazon, so this switch limits the areal heat + capacity to 1.15e5 J kg\ :sup:`-1` m\ :sup:`-2`, which is the value + calculated by the default broadleaf tree height of 19.01 m. + + TRUE + Vegetation areal heat capacity limited. + + FALSE + Vegetation areal heat capacity unlimited. + +.. nml:member:: l_sugar + + :type: logical + :default: F + + Switch for using the SUGAR carbohydrate model (:ref:`Jones et al., (2020)`) + + TRUE + Respiration is calculated using the SUGAR carbohydrate model + + FALSE + SUGAR is not used + + .. note:: The option :nml:mem:`JULES_VEGETATION::l_sugar` = T + is still in development. Users should ensure that results + are as expected, and provide feedback where deficiencies + are identified. + +.. nml:member:: l_red + + :type: logical + :default: F + + Switch for using the Robust Ecosystem Demography model (:ref:`Argles et al., (2020)`) + + TRUE + Robust Ecosystem Demography is used. + + FALSE + Robust Ecosystem Demography is not used. + + Only use if :nml:mem:`l_triffid` = TRUE. + + +.. nml:group:: Only used with the Farquhar model of leaf photosynthesis (:nml:mem:`photo_model` = 2). + + .. nml:member:: photo_acclim_model + + :type: integer + :permitted: 0, 1, 2, or 3 + :default: None + + Choice for model of thermal response of photosynthetic capacity. + Possible values are: + + 0. | No adaptation or acclimation. + + 1. | Thermal adaptation - plant response to temperature varies geographically in response to a static "home" temperature. + + 2. | Thermal acclimation - plant response to temperature varies geographically and temporally in response to a dynamic "growth" temperature. + + 3. | Thermal adaptation and acclimation - plant response to temperature varies geographically and temporally in response to a static "home" temperature and a dynamic "growth" temperature. + + .. note:: When :nml:mem:`photo_acclim_model` = 1 or 3 is used, the user must supply the long-term home temperature as ancillary field ``t_home_gb`` in :nml:lst:`JULES_VEGETATION_PROPS`. When :nml:mem:`photo_acclim_model` = 2 or 3 is used, the user must supply the running mean growth temperature as initial condition ``t_growth_gb`` in :nml:lst:`JULES_INITIAL`. + + + .. nml:member:: photo_act_model + + :type: integer + :permitted: 1 or 2 + :default: None + + Choice of model for the activation energies of J\ :sub:`max` and V\ :sub:`cmax`. + + 1. | Activation energies vary by PFT but not by land point, and are NOT subject to acclimation. + + 2. | Activation energies vary by land point but not by PFT, and are subject to acclimation. + + .. note:: When :nml:mem:`photo_act_model` = 1 is used, activation energies are calculated using :nml:mem:`JULES_PFTPARM::act_jmax_io` and :nml:mem:`JULES_PFTPARM::act_vcmax_io`. When :nml:mem:`photo_act_model` = 2 is used, activation energies are calculated using :nml:mem:`act_j_coef` and :nml:mem:`act_v_coef`. + + .. warning:: + A value of 1 (PFT-dependent) must be used if :nml:mem:`photo_acclim_model` = 0 (no adaptation or acclimation). + + + .. nml:member:: photo_jv_model + + :type: integer + :permitted: 1 or 2 + :default: None + + Choice for model of for the variation of J\ :sub:`25`/V\ :sub:`25`. + + 1. | J\ :sub:`25` is found by scaling V\ :sub:`25` by the given ratio J\ :sub:`25`/V\ :sub:`25`, that is, all the variation in the ratio comes from varying J\ :sub:`25` (while V\ :sub:`25` remains fixed). + + 2. | J25 and V25 are calculated assuming that the total amount of nitrogen allocated to photosynthesis remains constant, thus any change in J25 requires a compensatory change in V25 - as used in :ref:`Mercado et al. (2018)`. + + .. warning:: + A value of 1 (simple scaling) must be used if :nml:mem:`photo_acclim_model` = 0 (no adaptation or acclimation). + + + +.. nml:group:: Only used with :nml:mem:`photo_jv_model` = 2. + + + .. nml:member:: n_alloc_jmax + + :type: real + :default: None + + Constant relating nitrogen allocation to J\ :sub:`max` (mol CO\ :sup:`2` m\ :sup:`-2` s\ :sup:`-1` [kg m\ :sup:`-2`]\ :sup:`-1`). This is 5.3 in Eq.5 of :ref:`Mercado et al. (2018)`. + + + .. nml:member:: n_alloc_vcmax + + :type: real + :default: None + + Constant relating nitrogen allocation to V\ :sub:`cmax` (mol CO\ :sup:`2` m\ :sup:`-2` s\ :sup:`-1` [kg m\ :sup:`-2`]\ :sup:`-1`). This is 3.8 in Eq.5 of :ref:`Mercado et al. (2018)`. + + + +.. nml:group:: Only used with thermal adaptation or acclimation of photosynthesis (:nml:mem:`photo_acclim_model` = 1, 2 or 3). + + The thermal adaptation/acclimation scheme in JULES is structured following Eq. 13 of :ref:`Kumarathunge et al. (2019)`, in which C3 photosynthetic capacity is allowed to vary at each land point as a function of a static home temperature (T\ :sub:`h`) and a dynamic growth temperature (T\ :sub:`g`). This is achieved by calculating five parameters used in the Farquhar photosynthesis scheme as functions of those temperature fields, rather than using fixed parameters from :nml:lst:`JULES_PFTPARM`. Each parameter, Q, is calculated as a linear function of T\ :sub:`h` and T\ :sub:`g`: + + Q(T\ :sub:`h`, T\ :sub:`g`) = Q\ :sub:`coef`\ (0) + Q\ :sub:`coef`\ (1) T\ :sub:`h` + Q\ :sub:`coef`\ (2) T\ :sub:`g`. + + The following namelist members specify the coefficients, Q\ :sub:`coef`, used for each parameter. Note that, in each case, the units for Q\ :sub:`coef`\ (1) and Q\ :sub:`coef`\ (2) have an extra factor K\ :sup:`-1` relative to the units for Q\ :sub:`coef`\ (0). This structure can be configured to represent the acclimation scheme of :ref:`Kattge and Knorr (2007)`, as used by :ref:`Mercado et al. (2018)`, and the scheme of :ref:`Kumarathunge et al. (2019)`. + + .. note:: If :nml:mem:`photo_acclim_model` = 1 is used all Q\ :sub:`coef`\ (2) must equal 0.0, and if :nml:mem:`photo_acclim_model` = 2 is used all Q\ :sub:`coef`\ (1) must equal 0.0. + + .. nml:member:: act_j_coef + + :type: real(3) + :default: None + + Coefficients for the activation energy for J\ :sub:`max` (J mol\ :sup:`-1` and J mol\ :sup:`-1` K\ :sup:`-1`). Replaces the use of :nml:mem:`JULES_PFTPARM::act_jmax_io`. + + + .. nml:member:: act_v_coef + + :type: real(3) + :default: None + + Coefficients for the activation energy for V\ :sub:`cmax` (J mol\ :sup:`-1` and J mol\ :sup:`-1` K\ :sup:`-1`). Replaces the use of :nml:mem:`JULES_PFTPARM::act_vcmax_io`. + + + .. nml:member:: dsj_coef + + :type: real(3) + :default: None + + Coefficients for entropy factor for J\ :sub:`max` (J mol\ :sup:`-1` K\ :sup:`-1` and J mol\ :sup:`-1` K\ :sup:`-2`). Replaces the use of :nml:mem:`JULES_PFTPARM::deact_jmax_io`. + + + .. nml:member:: dsv_coef + + :type: real(3) + :default: None + + Coefficients for the entropy factor for V\ :sub:`cmax` (J mol\ :sup:`-1` K\ :sup:`-1` and J mol\ :sup:`-1` K\ :sup:`-2`). Replaces the use of :nml:mem:`JULES_PFTPARM::deact_vcmax_io`. + + + .. nml:member:: jv25_coef + + :type: real(3) + :default: None + + Coefficients for the ratio J\ :sub:`25`/V\ :sub:`25` (mol electrons [mol\ :sup:`-1` CO\ :sub:`2`] and (mol electrons [mol\ :sup:`-1` CO\ :sub:`2`] K\ :sup:`-1`). Replaces the use of :nml:mem:`JULES_PFTPARM::jv25_ratio_io`. + + +.. nml:group:: Only used with thermal acclimation of photosynthesis (:nml:mem:`photo_acclim_model` = 2 or 3). + + .. nml:member:: n_day_photo_acclim + + :type: real + :default: None + + Time constant (days) for the exponential moving average of temperature that is used as the growth temperature. Given a step function as input, the smoothed output has fallen to 1/e (approx. 37%) of the initial value after this number of days. + + +.. nml:member:: l_croprotate + + :type: logical + :default: F + + Switch that enables sequential cropping (crop rotations). + Only used + if :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0 and + if :nml:mem:`JULES_VEGETATION::l_prescsow` = T. + + TRUE + Sowing dates and latest harvest dates prescribed in + :nml:lst:`JULES_CROP_PROPS` are used. The method is implemented in + :ref:`Mathison et al. (2019)`. + + FALSE + The crop model is used in its standard form with a single crop per year + +.. _References_vegetation: + +``JULES_VEGETATION`` references +------------------------------- +* Argles, A. P. K., Moore, J. R., Huntingford, C., Wiltshire, A. J., + Harper, A. B., Jones, C. D., and Cox, P. M.: Robust Ecosystem Demography + (RED version 1.0): a parsimonious approach to modelling vegetation + dynamics in Earth system models, Geosci. Model Dev., 13, 4067–4089, + https://doi.org/10.5194/gmd-13-4067-2020 +* Best et al., 2011, The Joint UK Land Environment Simulator (JULES), + model description – Part 1: Energy and water fluxes, Geosci. Model + Dev., https://doi.org/10.5194/gmd-4-677-2011. +* Clark et al., 2011, The Joint UK Land Environment Simulator (JULES) + 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 +* Harman, I.N. & Finnigan, J.J. (2008), Scalar Concentration Profiles in the + Canopy and Roughness Sublayer. Boundary-Layer Meteorol. + 129: 323. https://doi.org/10.1007/s10546-008-9328-4 +* HCTN24, Hadley Centre Technical Note 24, available from `the Met Office Library + `_. + For ease the direct link to this document is: + `HCTN24 "Description of the "TRIFFID" Dynamic Global Vegetation Model" `_. +* Jogireddy, V., Cox, P. M., Huntingford, C., Harding, R. J., and + Mercado, L. M.: An improved description of canopy light + interception for use in a GCM land-surface scheme: calibration and + testing against carbon fluxes at a coniferous forest, Hadley Centre + Technical Note 63, Hadley Centre, Met Office, Exeter, + UK, 2006. https://digital.nmla.metoffice.gov.uk/IO_7873ea05-61ec-4615-b030-6bc33397d675 +* Kattge, J. and Knorr, W., 2007, + Temperature acclimation in a biochemical model of photosynthesis: + a reanalysis of data from 36 species, + Plant, Cell and Environment, 30: 1176--1190, + https://doi.org/10.1111/j.1365-3040.2007.01690.x. +* Kattge, J. , Knorr, W. , Raddatz, T. and Wirth, C. (2009), + Quantifying photosynthetic capacity and its relationship to leaf + nitrogen content for global-scale terrestrial biosphere + models. Global Change Biology, 15: + 976-991. https://doi.org/doi:10.1111/j.1365-2486.2008.01744.x +* Kumarathunge, D. P. et al (2019), Acclimation and adaptation components of + the temperature dependence of plant photosynthesis at the global scale, New + Phytologist, 222: 768-784, https://doi.org/10.1111/nph.15668 +* Massman, W. J. (1997), An Analytical One-Dimensional Model of + Momentum Transfer by Vegetation of Arbitrary Structure, + Boundary-Layer Meteorol. 83: 407-421. +* Medlyn, B. E., Duursma, R. A., Eamus, D. , Ellsworth, D. S., + Prentice, I. C., Barton, C. V., Crous, K. Y., De angelis, P., + Freeman, M. and Wingate, L. (2011), Reconciling the optimal and + empirical approaches to modelling stomatal conductance. Global + Change Biology, 17: + 2134-2144. https://doi.org/10.1111/j.1365-2486.2010.02375.x +* Medlyn, B. E., Duursma, R. A., Eamus, D. , Ellsworth, D. S., + Prentice, I. C., Barton, C. V., Crous, K. Y., De angelis, P., + Freeman, M. and Wingate, L. (2012), Reconciling the optimal and + empirical approaches to modelling stomatal conductance. Global + Change Biology, 18: + 3476-3476. https://doi.org/10.1111/j.1365-2486.2012.02790.x. +* Mercado, L. M., Huntingford, C., Gash, J. H. C., Cox, P. M., and + Jogireddy, V.: Improving the representation of radiative + interception and photosynthesis for climate model applications, + Tellus B, 59, + 553–565, 2007. https://doi.org/10.1111/j.1600-0889.2007.00256.x +* Mercado et al., 2018, Large sensitivity in land carbon storage due to + geographical and temporal variation in the thermal response of + photosynthetic capacity, New Phytologist, 218: 1462--1477, + https://doi.org/10.1111/nph.15100. +* Sellers et al., 1992, Canopy reflectance, photosynthesis, and + transpiration. III. A reanalysis using improved leaf models and a + new canopy integration scheme. Remote Sens. Environ., 42, 187-216, + https://doi.org/10.1016/0034-4257(92)90102-P +* Wang, W. (2012), An Analytical Model for Mean Wind Profiles in + Sparse Canopies. Boundary-Layer Meteorol + 142: 383. https://doi.org/10.1007/s10546-011-9687-0 +* Mathison, C , Challinor, A. J., Deva, C., Falloon, P., Garrigues, S., + Moulin, S., Williams, K., and Wiltshire, A. (2019), + Developing a sequential cropping capability in the JULESvn5.2 + land–surface model, Geosci. Model Dev. Discuss., + https://doi.org/10.5194/gmd-2019-85, in review, 2019. +* Jones et al., 2020, The impact of a simple representation of + non-structural carbohydrates on the simulated response of tropical + forests to drought, Biogeosciences, 17: 3589--3612. + https://doi.org/10.5194/bg-17-3589-2020 diff --git a/doc/source/namelists/jules_water_resources.nml.rst b/doc/source/namelists/jules_water_resources.nml.rst new file mode 100644 index 00000000..70af6002 --- /dev/null +++ b/doc/source/namelists/jules_water_resources.nml.rst @@ -0,0 +1,250 @@ +``jules_water_resources.nml`` +============================= + +This file sets options for water resource modelling. It contains a single namelist called :nml:lst:`JULES_WATER_RESOURCES`. + +.. warning:: + The water resource code in JULES is still in development. A limited parameterisation exists but it should be used with caution while development continues. At present all demands for water can only be met by abstraction from the same gridbox as where the demand is, which can lead to unrealistically high estimates of water shortage where in reality water infrastructure is used to move water between locations. Consult the developers for further information. + + +``JULES_WATER_RESOURCES`` namelist members +------------------------------------------ + +.. nml:namelist:: JULES_WATER_RESOURCES + +.. nml:member:: l_water_resources + + :type: logical + :default: F + + Switch to enable modelling of water resources. + + TRUE + Water resources are modelled. + This also requires that river routing is selected (:nml:mem:`JULES_RIVERS::l_rivers` = TRUE). + + FALSE + No water resources. In this case no further values from this namelist are required. + + +.. nml:member:: nstep_water_res + + :type: integer + :permitted: > 0 + :default: none + + The number of model timesteps per water resource timestep. (The main model timestep is given by :nml:mem:`JULES_TIME::timestep_len`.) + + For example, :nml:mem:`nstep_water_res` = 12 means that demands for water will be accumulated over 12 model timesteps before the water resource code is called on the 12th timestep. + + The water resource and river routing models must be in synchrony (i.e. be called on the same timesteps). + + + +.. nml:group:: Switches that control which water sectors are considered. + + + .. nml:member:: l_water_domestic + + :type: logical + :default: F + + Switch for modelling of water for domestic use. + + TRUE + Consider demand for water for domestic use. This requires that the domestic demand is prescribed as an input to the model (see :doc:`prescribed_data.nml`). + + FALSE + Do not consider domestic demand. + + + .. nml:member:: l_water_environment + + :type: logical + :default: F + + Switch for modelling of water for environmental flow requirements. + + TRUE + Consider demand for water for environmental flows. This option is not allowed until further developments are complete. + + FALSE + Do not consider environmental demand. + + .. note:: + At present :nml:mem:`l_water_environment` must be FALSE as the parameterisation is not yet complete. In the meanwhile this switch is provided to allow the developers to test code. + + + .. nml:member:: l_water_industry + + :type: logical + :default: F + + Switch for modelling of water for industrial use. This requires that the industrial demand is prescribed as an input to the model (see :doc:`prescribed_data.nml`). + + TRUE + Consider demand for water for industrial use. + + FALSE + Do not consider industrial demand. + + + .. nml:member:: l_water_irrigation + + :type: logical + :default: F + + Switch for modelling of water for irrigation. + + TRUE + Consider demand for water for irrigation. This must be used with :nml:mem:`JULES_IRRIG::l_irrig_dmd` = TRUE (to activate the inclusion of irrigation in other aspects of the model) and :nml:mem:`JULES_IRRIG::l_irrig_limit` = FALSE (to avoid triggering an alternative approach to calculating the water available for irrigation). + + FALSE + Do not consider irrigation demand. + + + .. nml:member:: l_water_livestock + + :type: logical + :default: F + + Switch for modelling of water for livestock. + + TRUE + Consider demand for water for livestock. This requires that the livestock demand is prescribed as an input to the model (see :doc:`prescribed_data.nml`). + + FALSE + Do not consider livestock demand. + + + .. nml:member:: l_water_transfers + + :type: logical + :default: F + + Switch for modelling of water for transfers. + + TRUE + Consider demand for water for transfers. This requires that the demand for transfers is prescribed as an input to the model (see :doc:`prescribed_data.nml`). This option is not allowed until further developments are complete. + + FALSE + Do not consider transfers. + + .. note:: + At present :nml:mem:`l_water_transfers` must be FALSE as the parameterisation is not yet complete. In the meanwhile this switch is provided to allow the developers to test code. + + +.. nml:group:: Switches that control prioritisation of demands. + + + .. nml:member:: l_prioritise + + :type: logical + :default: F + + Switch controlling prioritisation of demands. + + TRUE + Rank demands from sectors in priority order. + + FALSE + No prioritisation. No further items from this group are required. + + + .. nml:member:: priority + + :type: character + :default: none + + A list of water sector names, in order of decreasing priority - see the table below for valid names. Only used if :nml:mem:`l_prioritise` = TRUE. All active sectors (as selected by switches such as :nml:mem:`l_water_domestic`) must be represented in this list. The same prioritisation is used for all points in the domain. + + .. tabularcolumns:: |p{2cm}|p{9cm}| + + +------------+----------------------+ + | Name | Description | + +============+======================+ + | ``dom`` | Domestic use | + +------------+----------------------+ + | ``env`` | Environmental flows | + +------------+----------------------+ + | ``ind`` | Industrial use | + +------------+----------------------+ + | ``irr`` | Irrigation | + +------------+----------------------+ + | ``liv`` | Livestock use | + +------------+----------------------+ + | ``tra`` | Water transfers | + +------------+----------------------+ + + +.. nml:member:: nr_gwater_model + + :type: integer + :permitted: 0,1,2 + :default: none + + Choice for the model of non-renewable groundwater. Non-renewable groundwater as defined here is water that is not otherwise explicitly included in the model. It is an idealised, infinite source of water which is typically intended to allow consideration of pumping of groundwater from deep reserves that are difficult to quantify. + + Possible values are: + + 0. | No non-renewable groundwater is considered. + + 1. | Non-renewable groundwater is used as a last resort, when no other sources of water are available. + + 2. | Non-renewable groundwater is used as as 'part of the mix', in conjunction with other sources of water. + + +.. nml:group:: Switches that control how surface and groundwater sources are used. + + + .. nml:member:: partition_method + + :type: integer + :permitted: 0,1,2 + :default: none + + Method used to calculate the target for the fraction of demand that will be met from surface water versus groundwater. + + Possible values are: + + 0. | No target required. This value is required when either or both of groundwater and surface water are not included in the model configuration. + + 1. | The target will be read from an ancillary file (see :nml:lst:`JULES_WATER_RESOURCES_PROPS`). + + 2. | The target will be calculated based on the current availability of water in surface and groundwater stores, using parameter :nml:mem:`sfc_water_factor`. + + + .. nml:member:: sfc_water_factor + + :type: real + :permitted: >= 0 + :default: none + + The weight (a factor) applied to surface water when calculating the target for the fraction of demand that will be met from surface water. The target is calculated as sfc_water_factor x surface_water_available / ( sfc_water_factor x surface_water_available + groundwater_available ). Values > 1 mean the target will increasingly be to use surface water rather than groundwater. + + +.. nml:member:: rf_domestic + + :type: real + :permitted: 0-1 + :default: none + + The fraction of water that is returned after abstraction for domestic use (via sewage systems etc.). Only used if :nml:mem:`l_water_domestic` = TRUE. + + +.. nml:member:: rf_industry + + :type: real + :permitted: 0-1 + :default: none + + The fraction of water that is returned after abstraction for industrial use. Only used if :nml:mem:`l_water_industry` = TRUE. + + +.. nml:member:: rf_livestock + + :type: real + :permitted: 0-1 + :default: none + + The fraction of water that is returned after abstraction for livestock. Only used if :nml:mem:`l_water_livestock` = TRUE. diff --git a/doc/source/namelists/model_environment.nml.rst b/doc/source/namelists/model_environment.nml.rst new file mode 100644 index 00000000..5572db50 --- /dev/null +++ b/doc/source/namelists/model_environment.nml.rst @@ -0,0 +1,84 @@ +``model_environment.nml`` +========================= + + +This file sets the model environment options e.g. whether JULES is +coupled to the UM or run in a standalone environment. It contains one +namelist called :nml:lst:`JULES_MODEL_ENVIRONMENT`. + +There are many JULES science options that are in shared namelists, so +they can be read both by standalone and by a model driving JULES +e.g. the UM. However some options either make no scientific sense or +the necessary input data are not available to the environment in which +JULES is being driven as the plumbing has not yet been done. This +causes problems for example when creating standalone apps from UM +configurations. This namelist allows the environment in which JULES is +being run to be specified so that options that are unavailable can be +made inaccessible via the metadata and thus will not appear in the +gui. Warnings can also be issued if options are inappropriately set. + +This namelist also describes the flavour of the land surface model +being used. CABLE is in the process of being incorporated into JULES +and other flavours of JULES is in development e.g. a standalone rivers +app. + +``JULES_MODEL_ENVIRONMENT`` namelist members +-------------------------------------------- + +.. nml:namelist:: JULES_MODEL_ENVIRONMENT + +.. nml:member:: l_jules_parent + + :type: integer + :default: imdi + + Switch to identify the environment in which JULES is being run. The + switch should only be used to allow science options, which are not + available in the specified model environment, to be trigger ignored + and checked that they are set appropriately at run-time. + + = ============================== + 0 JULES is being run standalone. |br| + Any options that are only available to the parent model (e.g. the UM) will be trigger ignored. + 1 JULES is being run coupled to the UM. |br| + 2 JULES is being run coupled via OASIS (available to Rivers-only executable only). |br| + Options not available to the UM are trigger-ignored. + = ============================== + + .. warning:: + No science code should be associated with this switch, only what + science options are available. + + .. note:: + The metadata of the parent model only actually allows the + appropriate option to be specified i.e. in standalone only 0 is + permitted and in the UM only 1 is permitted. Any other parent + models are listed here for information only. It is not + appropriate to include a list of the unavailable options + here. However, information for namelists that have been + consolidated will appear in the following checking routines as + they are completed. + + * `src/control/standalone/check_unavailable_options_mod.F90 + `_ + * `src/control/um/check_jules_unavailable_options_mod.F90 + `_ + +.. nml:member:: lsm_id + + :type: integer + :default: MDI + + Switch for land surface model flavour. + + = ======================== + 1 JULES land surface model + 2 CABLE land surface model + = ======================== + + .. note:: + The CABLE model has not yet been implemented within the JULES repository. + +.. |br| raw:: html + +
    diff --git a/doc/source/namelists/model_grid.nml.rst b/doc/source/namelists/model_grid.nml.rst new file mode 100644 index 00000000..064b8d10 --- /dev/null +++ b/doc/source/namelists/model_grid.nml.rst @@ -0,0 +1,928 @@ +``model_grid.nml`` +================== + + +This file sets up the grid configuration for the run. It contains seven namelists - :nml:lst:`JULES_INPUT_GRID`, :nml:lst:`JULES_LATLON`, :nml:lst:`JULES_LAND_FRAC`, :nml:lst:`JULES_MODEL_GRID`, :nml:lst:`JULES_NLSIZES`, :nml:lst:`JULES_SURF_HGT` and :nml:lst:`JULES_Z_LAND` + +Each run of JULES involves two grids: the input grid and the model grid. The input grid is the grid on which all input data are held. The model grid is the set of points on which the model is run. The model grid is the grid of points that will be processed by JULES, and is a subset of the input grid. + +As discussed in :doc:`/input/principles`, the input grid consists of three pieces of information: + +#. Whether the grid is 1D or 2D. +#. The size of each dimension. +#. The name of each dimension in the input file(s). + +The latitude, longitude and land fraction of each point are then read in on the full input grid as specified by the namelists. A subset of the input grid to use as the model grid can then be specified in various ways described below (e.g. land points only, all points within certain latitude/longitude bounds). + +In most cases, the model grid will be represented internally as a vector of points, even when the input grid is 2D. Numerically, this makes no difference. The only time that the model grid will be 2D is when the input grid is 2D, :nml:mem:`JULES_MODEL_GRID::force_1d_grid` = F and the model grid is a contiguous rectangular subsection of the input grid. + + +``JULES_INPUT_GRID`` namelist members +------------------------------------- + +.. nml:namelist:: JULES_INPUT_GRID + +.. warning:: The dimension names specified in this namelist will be used for all input files. + +.. nml:member:: grid_is_1d + + :type: logical + :default: F + + Indicates if the input grid is 1D or 2D. + + TRUE + Variables have one grid dimension in the input file(s) - a points dimensions (e.g. a vector of land points with grid dimension "land"). + + FALSE + Variables have two grid dimensions in the input file(s) - an x and a y dimension. + + +.. nml:group:: Only used when :nml:mem:`grid_is_1d` = TRUE + + .. nml:member:: grid_dim_name + + :type: character + :default: "land" + + The name of the single grid dimension. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + + .. nml:member:: npoints + + :type: integer + :permitted: >= 1 + :default: 0 + + The size of the single grid dimension. + + +.. nml:group:: Only used when :nml:mem:`grid_is_1d` = FALSE + + .. nml:member:: x_dim_name + + :type: character + :default: "x" + + The name of the x dimension (it may, but does not have to, coincide with :nml:mem:`JULES_RIVERS_PROPS::x_dim_name`). + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should be the name of the dimension in the input file(s). + + + .. nml:member:: y_dim_name + + :type: character + :default: "y" + + The name of the y dimension (it may, but does not have to, coincide with :nml:mem:`JULES_RIVERS_PROPS::y_dim_name`). + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should be the name of the dimension in the input file(s). + + + .. nml:member:: nx + + :type: integer + :permitted: >= 1 + :default: 0 + + The size of the x dimension. + + + .. nml:member:: ny + + :type: integer + :permitted: >= 1 + :default: 0 + + The size of the y dimension. + + +.. nml:member:: time_dim_name + + :type: character + :default: "time" + + The name of the time dimension in any input files containing time varying data. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + +.. nml:member:: pft_dim_name + + :type: character + :default: "pft" + + The dimension name used when variables have an additional dimension of size :nml:mem:`JULES_SURFACE_TYPES::npft`. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + +.. nml:member:: cpft_dim_name + + :type: character + :default: "cpft" + + The dimension name used when variables have an additional dimension of size :nml:mem:`JULES_SURFACE_TYPES::ncpft`. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + +.. nml:member:: nvg_dim_name + + :type: character + :default: "nvg" + + The dimension name used when variables have an additional dimension of size :nml:mem:`JULES_SURFACE_TYPES::nnvg`. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + +.. nml:member:: type_dim_name + + :type: character + :default: "type" + + The dimension name used when variables have an additional dimension of size ``ntype``. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + +.. nml:member:: tile_dim_name + + :type: character + :default: "tile" + + The dimension name used when variables have an additional dimension of size ``nsurft``. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + +.. nml:member:: soil_dim_name + + :type: character + :default: "soil" + + The dimension name used when variables have an additional dimension of size :nml:mem:`JULES_SOIL::sm_levels`. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + +.. nml:member:: snow_dim_name + + :type: character + :default: "snow" + + The dimension name used when variables have an additional dimension of size :nml:mem:`JULES_SNOW::nsmax`. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + +.. nml:member:: sclayer_dim_name + + :type: character + :default: "sclayer" + + The dimension name used for the soil biogeochemistry when layered soil is used i.e. :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = TRUE. When :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = TRUE the soil biogeochemistry has the same number of layers as the soil hydrology (:nml:mem:`JULES_SOIL::sm_levels`). When :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = FALSE the soil biogeochemistry represents a single bulk layer. Despite the similar name, this parameter is unrelated to :nml:mem:`JULES_SOIL_ECOSSE::dim_cslayer`. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + +.. nml:member:: scpool_dim_name + + :type: character + :default: "scpool" + + The dimension name used when variables have an additional dimension of size ``dim_cs1``. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + +.. nml:member:: bedrock_dim_name + + :type: character + :default: "bedrock" + + The dimension name used when variables have an additional dimension of size :nml:mem:`JULES_SOIL::ns_deep`. + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + +.. nml:member:: tracer_dim_name + + :type: character + :default: "tracer" + + The dimension name used when variables have an additional dimension of size :nml:mem:`JULES_DEPOSITION::ndry_dep_species` (e.g. chemical tracers in the atmosphere). + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + +.. nml:member:: bl_level_dim_name + + :type: character + :default: "bllevel" + + The dimension name used when variables have an additional dimension of size :nml:mem:`JULES_NLSIZES::bl_levels` (e.g. variables on atmospheric boundary layer levels). + + .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). + + +``JULES_LATLON`` namelist members +--------------------------------- + +.. nml:namelist:: JULES_LATLON + + +.. nml:group:: Members used to determine how gridpoint location variables are set + + + .. nml:member:: read_from_dump + + :type: logical + :default: F + + TRUE + Populate variables associated with this namelist from the dump file. All other namelist members are ignored. + + FALSE + Use the other namelist members to determine how to populate variables. + + + .. nml:member:: l_coord_latlon + + :type: logical + :default: F + + TRUE + The coordinate system used for the model grid is latitude and longitude. + + FALSE + The model grid is defined by projection coordinates other than latitude and longitude (e.g. northings and eastings, or a rotated grid). + + + .. nml:member:: nvars + + :type: integer + :permitted: >= 2 + :default: 0 + + The number of location variables that will be provided (see :ref:`list-of-grid-location-params`). + + + .. nml:member:: var + + :type: character(nvars) + :default: None + + List of location variable names as recognised by JULES (see :ref:`list-of-grid-location-params`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + + + .. nml:member:: use_file + + :type: logical(nvars) + :default: T + + For each JULES variable specified in :nml:mem:`var`, this indicates if it should be read from the specified file or whether a constant value is to be used. + + TRUE + The variable will be read from the file. + + FALSE + The variable will be set to a constant value everywhere using :nml:mem:`const_val` below. + + + .. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = TRUE, this is the name of the variable in the file containing the data. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + This is not used for variables where :nml:mem:`use_file` = FALSE, but a placeholder must still be given in that case. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + + + .. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name in place of the variable name substitution string. + + If the file name does not use variable name templating, this is not used. + + + .. nml:member:: const_val + + :type: real(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var` where :nml:mem:`use_file` = FALSE, this is a constant value that the variable will be set to at every point. + + This is not used for variables where :nml:mem:`use_file` = TRUE, but a placeholder must still be given in that case. + + + .. nml:member:: file + + :type: character + :default: None + + The file to read ancillary properties from. + + If :nml:mem:`use_file` is FALSE for every variable, this will not be used. + + This file name can use :doc:`variable name templating `. + + +.. _list-of-grid-location-params: + +List of grid location properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following table summarises ancillary fields that give the location and related characteristics of each point on the grid, specified from an ancillary file if :nml:mem:`JULES_LATLON::use_file` = TRUE. + +.. tabularcolumns:: |p{3cm}|L| + ++----------------------------+------------------------------------------------------------------------------------------+ +| Name | Description | ++============================+==========================================================================================+ +| ``latitude`` | Latitude of each point. Always required. | +| | | ++----------------------------+------------------------------------------------------------------------------------------+ +| ``longitude`` | Longitude of each point. Always required. | +| | Values in the range -180 to 360 are allowed. | ++----------------------------+------------------------------------------------------------------------------------------+ +| ``projection_x_coord`` | Values of the projection coordinate in the x direction. | +| | This is only required if :nml:mem:`l_coord_latlon` = FALSE. | +| | Note that these can have any valid unit. | ++----------------------------+------------------------------------------------------------------------------------------+ +| ``projection_y_coord`` | Values of the projection coordinate in the y direction. | +| | 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 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. + + +``JULES_LAND_FRAC`` namelist members +------------------------------------ + +.. nml:namelist:: JULES_LAND_FRAC + +Land fraction is the fraction of each gridbox that is land. Currently, JULES considers any gridbox with land fraction > 0 to be 100% land, and all others to be 100% sea (or sea-ice). Land fraction data can be used to select only land points from the full input grid (see below). + +.. 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: + + +.. nml:member:: file + + :type: character + :default: None + + The name of the file to read land fraction data from. + + +.. nml:member:: land_frac_name + + :type: character + :default: 'land_fraction' + + The name of the variable containing the land fraction data. + + In the file, the variable must have no levels dimensions and no time dimension. + + + +``JULES_MODEL_GRID`` namelist members +------------------------------------- + +.. nml:namelist:: JULES_MODEL_GRID + +Members of this namelist are used to select the points to be modelled from the input grid. This can be done in various ways (see the :ref:`grid-examples`). + + +.. nml:member:: land_only + + :type: logical + :default: T + + TRUE + Model land points only (from the points that are selected with other options). + + FALSE + Model all selected points. + + If :nml:mem:`use_subgrid` = FALSE (see below), the land points will be extracted from the full input grid. + + If :nml:mem:`use_subgrid` = TRUE, then the subgrid extraction takes place first, and the land points will be extracted from the specified subgrid. + + +.. nml:member:: force_1d_grid + + :type: logical + :default: F + + TRUE + Force the model grid to be 1D, even if it would otherwise have been 2D. + + FALSE + The model grid takes its default shape. + + +.. nml:member:: use_subgrid + + :type: logical + :default: F + + TRUE + The model grid is a subset of the full input grid, specified using some valid combination of the options below. + + FALSE + The model grid is the full input grid. + + +.. nml:group:: Only used if :nml:mem:`use_subgrid` = TRUE + + .. nml:member:: l_bounds + + :type: logical + :default: None + + TRUE + Subset of points to model will be selected using bounds for the coordinates variables. + + FALSE + Subset of points to model will be selected using a list of coordinate pairs for each point. + + If :nml:mem:`JULES_LATLON::l_coord_latlon` = TRUE, the coordinates used here are latitude and longitude. + + If :nml:mem:`JULES_LATLON::l_coord_latlon` = FALSE, the coordinates used here are the values stored in the variables projection_x_coord and projection_y_coord. + + + .. nml:group:: Only used if :nml:mem:`l_bounds` = TRUE + + .. nml:member:: y_bounds + + :type: real(2) + :default: None + + The lower and upper bounds (in that order) for the y coordinate used to select points. Assuming that the coordinate is latitude (see :nml:mem:`JULES_LATLON::l_coord_latlon`) the model grid will comprise the points where ``y_bounds(1) <= latitude <= y_bounds(2)``. + + + .. nml:member:: x_bounds + + :type: real(2) + :default: None + + The lower and upper bounds (in that order) for the x coordinate used to select points. Assuming that the coordinate is longitude (see :nml:mem:`JULES_LATLON::l_coord_latlon`) the model grid will comprise the points where ``x_bounds(1) <= longitude <= x_bounds(2)``. + + If the x coordinate is longitude, the values of x_bounds should lie in the range [-180, 360]. A special case is that in which the desired subgrid straddles the edge of a global input grid. For example, if the input grid has longitudes in [0, 360] and a domain of 20 degrees of longitude centred on 0degE is required, this should be indicated using ``xbounds=-10,10`` (not xbounds=360,370 because values > 360 are not recognised). In this case the JULES code recognises the cyclic nature of longitude and correctly picks up points in both hemispheres, even though -10degE is outwith the longitude values in the input grid. + + + .. nml:group:: Only used if :nml:mem:`l_bounds` = FALSE + + .. nml:member:: npoints + + :type: integer + :permitted: >= 1 + :default: 0 + + The number of points to model. + + + .. nml:member:: points_file + + :type: character + :default: None + + The name of the file containing the coordinates for each point. + + If :nml:mem:`JULES_LATLON::l_coord_latlon` = TRUE, the coordinates used here are latitude and longitude. Each line in the file should contain the latitude and longitude (in that order) for a point. + + If :nml:mem:`JULES_LATLON::l_coord_latlon` = FALSE, the coordinates used here are the values stored in the variables projection_x_coord and projection_y_coord. Each line in the file should contain the value for projection_y_coord and projection_x_coord (in that order; note this is y then x) for a point. + + An error is raised and the run terminates if any coordinate pair does not match to a location in the input grid. + + + +``JULES_NLSIZES`` namelist members +------------------------------------- + +.. nml:namelist:: JULES_NLSIZES + +This namelist is used to set the number of levels in the boundary layer. + + +.. nml:member:: bl_levels + + :type: integer + :default: 1 + + Number of boundary layer levels. This is only used if atmospheric deposition is selected (:nml:mem:`JULES_DEPOSITION::l_deposition` = TRUE) in which case it is used to set the size of input fields. + + +``JULES_SURF_HGT`` namelist members +----------------------------------- + +.. nml:namelist:: JULES_SURF_HGT + +This namelist sets the elevation of each surface tile. Elevations can either be *relative to the gridbox mean* or *have constant elevation bands above sea-level*. + +If tile elevations are set relative to the gridbox mean, then the gridbox mean elevation is not required. The gridbox mean elevation is implicit in the near-surface meteorological data that are provided (higher locations will tend to be colder, have lower pressure, etc.). The elevation of each tile is used to alter the values of the air temperature and humidity (and possibly downwelling longwave, see :nml:mem:`JULES_SURFACE::l_elev_lw_down`) over that tile relative to the surface. + +If any tile uses absolute heights (i.e. :nml:mem:`JULES_SURF_HGT::l_elev_absolute_height` has at least one element that is .true.), then the gridbox mean elevation must also be supplied. This is read in from the optional :nml:lst:`JULES_Z_LAND` namelist which is described below. The model calculates elevations relative to the gridbox mean by taking the difference between the absolute elevation and the gridbox mean. + +If any tile uses absolute heights, then tile heights are set constant across a domain, regardless of whether each tile's height is specified as a relative offset or absolute. This makes it simple to set zero-offset heights for tiles that should not be considered in the elevation bands. It is no longer possible to have spatially varying tile heights if this option is used. + + +.. nml:member:: zero_height + + :type: logical + :default: T + + Switch used to simplify the initialisation of tile elevation. + + .. note:: If :nml:mem:`JULES_SURFACE::l_aggregate` = TRUE, this switch is also set to TRUE. + + TRUE + Set all surface tile elevations to zero. This is a very common configuration. + + FALSE + Set surface tile heights using specified data. + + +.. nml:group:: Only used if :nml:mem:`zero_height` = FALSE + + .. nml:member:: l_elev_absolute_height + + :type: logical(nsurft) + :default: F + + TRUE + Heights of surface tiles are absolute values above sea-level. If this option is used, then the elevation of the forcing data must also be provided (see :nml:lst:`JULES_Z_LAND` namelist below). + + FALSE + Surface tile heights are relative to the gridbox mean. + + + .. nml:member:: use_file + + :type: logical + :default: T + + This indicates if surface tile heights relative to the gridbox mean should be read from a specified file or namelist. + + TRUE + The variable will be read from a file if the input grid consists of more than location. + + FALSE + The variable will be read from a namelist if the input grid is for a single location. + +.. nml:group:: Only used if :nml:mem:`use_file` = TRUE + + .. nml:member:: file + + :type: character + :default: None + + The name of the file containing surface tile heights relative to the gridbox mean. + + .. nml:member:: surf_hgt_name + + :type: character + :default: 'surf_hgt' + + The name of the variable containing surface tile heights relative to the gridbox mean. In the file, the variable must have a single levels dimension of size ``nsurft`` called :nml:mem:`JULES_INPUT_GRID::tile_dim_name`. + +.. nml:group:: Only used if :nml:mem:`use_file` = FALSE + + .. nml:member:: surf_hgt_io + + :type: real(nsurft) + :default: None + + Surface tile heights relative to the gridbox mean for a single location. + + +``JULES_Z_LAND`` namelist members +----------------------------------- + +This is an optional namelist and only used if any surface tile has :nml:mem:`JULES_SURF_HGT::l_elev_absolute_height` = TRUE. The namelist sets values for the elevation bands and reads the elevation of the forcing data. + +.. nml:namelist:: JULES_Z_LAND + +.. nml:member:: surf_hgt_band + + :type: real(nsurft) + :default: None + + Spatially invariant elevation bands for each surface tile. These may be relative to the gridbox mean or absolute elevations above sea-level depending on :nml:mem:`JULES_SURF_HGT::l_elev_absolute_height`. + +.. nml:member:: use_file + + :type: logical + :default: T + + This indicates if the elevation of the forcing data should be read from a file or from a namelist. + + TRUE + The variable will be read from a file if the input grid consists of more than location. + FALSE + The variable will be read from a namelist if the input grid is for a single location. + +.. nml:group:: Used if :nml:mem:`JULES_Z_LAND::use_file` = TRUE + + .. nml:member:: file + + :type: character + :default: None + + The name of the file containing the elevation of the forcing data. + + .. nml:member:: z_land_name + + :type: character + :default: 'z_land' + + The name of the variable containing the elevation of the forcing data. In the file, the variable must have no level dimensions and no time dimensions. + +.. nml:group:: Used if :nml:mem:`JULES_Z_LAND::use_file` = FALSE + + .. nml:member:: z_land_io + + :type: real + :default: None + + Elevation of the forcing data for a single location. + +Example +~~~~~~~ + +The following gives an example of how you would set up the namelists to use elevation bands above sea-level. + +:: + + &JULES_SURF_HGT + + zero_height = .false., + + # No elevation correction to surface tiles 1 to 6, use elevation bands for surface tiles 7 to 9 + l_elev_absolute_height = 6*.false., 3*.true., + + / + + &JULES_Z_LAND + + # Set values for the elevation bands. + surf_hgt_band = 6*0.0, 1000.0, 2000.0, 3000.0, + + # Read the WFDEI forcing data elevation from a file + use_file = .true., + file = 'WFDEI-elevation.nc', + z_land_name = 'elevation' + + / + + +.. _grid-examples: + +Examples of grid setups +----------------------- + +A single location +~~~~~~~~~~~~~~~~~ + +:: + + &JULES_INPUT_GRID + nx = 1, + ny = 1 + / + + &JULES_LATLON + l_coord_latlon = T + nvars = 2, + var = 'latitude','longitude', + use_file = .false., .false., + const_val = 52.168, 5.744 + / + + &JULES_LAND_FRAC / + + &JULES_MODEL_GRID / + + &JULES_SURF_HGT + zero_height = T + / + +:nml:lst:`JULES_INPUT_GRID` + The default value of :nml:mem:`JULES_INPUT_GRID::grid_is_1d`, FALSE, is used. This means the user has to specify the extents, :nml:mem:`JULES_INPUT_GRID::nx` and :nml:mem:`JULES_INPUT_GRID::ny`, of the input grid. Since all the input data is ASCII, no dimension names are required. + +:nml:lst:`JULES_LATLON` + The latitude and longitude of the single location are specified directly in the namelist. :nml:mem:`JULES_LATLON::nvars` = 2 indicates that the two mandatory variables will be provided, and :nml:mem:`JULES_LATLON::var` = 'latitude','longitude' confirms that these are the latitude and longitude. :nml:mem:`JULES_LATLON::use_file` = .false. indicates that the values will be read from the namelist (not from another file) and the values are provided after :nml:mem:`JULES_LATLON::const_val`. + +:nml:lst:`JULES_LAND_FRAC` + The land fraction at the single location is assumed to be 100%, so nothing is required. + +:nml:lst:`JULES_MODEL_GRID` + Use default options to select the model grid (i.e. land points only from the full input grid). In this case, this leaves the single location as the model grid. + + +Examples of gridded runs +~~~~~~~~~~~~~~~~~~~~~~~~ + +All the examples in this section assume gridded NetCDF data. + +Specifying a 1D input grid +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this example, input files contain data on a vector of land points. The land points dimension is called "land". The time dimension for time-varying variables is called "time". The default dimension names are used for all additional dimensions (e.g. pft, tile). :: + + &JULES_INPUT_GRID + grid_is_1D = T, + + npoints = 15238, + grid_dim_name = "land", + + time_dim_name = "time" + / + +Specifying a 2D input grid +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this example, input files contain data on a 2D latitude/longitude grid. The x dimension is called "lon" and the y dimension is called "lat". The time dimension for time-varying variables is called "time". Variables with an extra tiles dimension use the dimension name "pseudo" for that dimension. All other additional dimensions use their default names. :: + + &JULES_INPUT_GRID + grid_is_1D = F, + + nx = 96, + ny = 56, + + x_dim_name = "lon", + y_dim_name = "lat", + + tile_dim_name = "pseudo", + + time_dim_name = "time" + / + +Specifying a subgrid using a given range of latitude and longitude +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This can be used with either a 1D or 2D input grid. :: + + &JULES_LATLON + l_coord_latlon = T, + nvars = 2, + var = 'latitude','longitude', + use_file = .true., .true., + file = 'lat_lon.nc', + / + + &JULES_LAND_FRAC + file = 'land_mask.nc', + + land_frac_name = 'land_frac' + / + + &JULES_MODEL_GRID + land_only = F, + + use_subgrid = T, + + l_bounds = T, + + y_bounds = 55.0 57.0, + x_bounds = -5.0 -3.0 + / + +This setup reads latitude, longitude and land fraction for each gridbox in the full input grid (1D or 2D) from the named variables in the specified files. + +In :nml:lst:`JULES_MODEL_GRID`, :nml:mem:`JULES_MODEL_GRID::use_subgrid` indicates that a subset of the input grid will be selected as the model grid. :nml:mem:`JULES_MODEL_GRID::l_bounds` then indicates that latitude and longitude bounds will be used to select the subgrid. :nml:mem:`JULES_MODEL_GRID::land_only` = FALSE means that sea and sea-ice points will remain in the model grid if any are selected. The model grid will then be a vector containing the selected points (those that fall within the latitude/longitude bounds), even if those points could be used to form a rectangular region. + +Specifying a subgrid using a given range of projection coordinates (not latitude and longitude) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This can be used with either a 1D or 2D input grid. :: + + &JULES_LATLON + l_coord_latlon = F, + nvars = 4, + var = 'latitude','longitude','projection_x_coord','projection_y_coord' + use_file = .true., .true., .true., .true., + file = 'lat_lon.nc', + / + + &JULES_LAND_FRAC + file = 'land_mask.nc', + + land_frac_name = 'land_frac' + / + + &JULES_MODEL_GRID + land_only = F, + + use_subgrid = T, + + l_bounds = T, + + y_bounds = 500.0 40500.0, + x_bounds = 25500.0 55500.0 + / + +In this setup :nml:mem:`JULES_LATLON::l_coord_latlon` = FALSE indicates that data will be read from a grid that is not defined by latitude and longitude - rather it uses other projection coordinates such as the northings and eastings of the Ordnance Survey (British) National Grid (BNG) OSGB36. The projection coordinates are read via the variables projection_x_coord and projection_y_coord. Note that the latitude and longitude of each point is also read in; JULES includes these in output files for reference, and they can also be required by the science code (e.g. for solar zenith angle). + +In :nml:lst:`JULES_MODEL_GRID`, :nml:mem:`JULES_MODEL_GRID::use_subgrid` indicates that a subset of the input grid will be selected as the model grid. :nml:mem:`JULES_MODEL_GRID::l_bounds` then indicates that bounding values of the projection coordinates will be used to select the subgrid. :nml:mem:`JULES_MODEL_GRID::land_only` = FALSE means that sea and sea-ice points will remain in the model grid if any are selected. The model grid will then be a vector containing the selected points (those that fall within the latitude/longitude bounds), even if those points could be used to form a rectangular region. + +Specifying a subgrid using a list of points +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This can be used with either a 1D or 2D input grid. :: + + &JULES_LATLON + l_coord_latlon = T, + nvars = 2, + var = 'latitude','longitude', + use_file = .true., .true., + file = 'lat_lon.nc', + / + + &JULES_LAND_FRAC + file = 'land_mask.nc', + + land_frac_name = 'land_frac' + / + + &JULES_MODEL_GRID + use_subgrid = T, + + l_bounds = F, + + npoints = 4, + points_file = 'points.txt' + / + +This setup reads latitude, longitude and land fraction for each gridbox in the full input grid (1D or 2D) from the named variables in the specified files. + +In :nml:lst:`JULES_MODEL_GRID`, :nml:mem:`JULES_MODEL_GRID::use_subgrid` indicates that a subset of the input grid will be selected as the model grid. :nml:mem:`JULES_MODEL_GRID::l_bounds` then indicates that a list of latitudes and longitudes will be used to select the subgrid. :nml:mem:`JULES_MODEL_GRID::land_only` is not given, meaning it takes its default value, TRUE. This means that any sea or sea-ice points specified in the list of points will be discarded. The model grid will then be a vector +containing the selected points (those with the given latitude/longitude). + +Assuming that the input grid is a 1 degree grid and the latitude and longitude are given at the centre of the gridbox, ``points.txt`` should look like the following:: + + 55.5 -4.5 + 55.5 -3.5 + 56.5 -4.5 + 56.5 -3.5 + +The only configuration that yields a 2D model grid +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + &JULES_INPUT_GRID + grid_is_1d = F, + + nx = 96, + ny = 56, + + # ... + / + + &JULES_LATLON + # + / + + &JULES_LAND_FRAC + # + / + + &JULES_MODEL_GRID + land_only = F + / + +In general, the only configuration that yields a 2D model grid is: + +* 2D input grid +* The model grid is the full input grid, including any non-land points + +If the input grid is a 2D region where every point is land (i.e. not the whole globe), then :nml:mem:`JULES_MODEL_GRID::land_only` = TRUE would also yield a 2D model grid. If any options are set that mean some points from the input grid are not modeled, the model grid will be a vector of points. Computationally, this makes no difference. diff --git a/doc/source/namelists/nveg_params.nml.rst b/doc/source/namelists/nveg_params.nml.rst new file mode 100644 index 00000000..cd0a1b6e --- /dev/null +++ b/doc/source/namelists/nveg_params.nml.rst @@ -0,0 +1,144 @@ +``nveg_params.nml`` +=================== + + +This file contains a namelist called :nml:lst:`JULES_NVEGPARM` that sets time-invariant parameters for non-vegetation surface types for the JULES land surface model. + +``JULES_NVEGPARM`` namelist members +----------------------------------- + +.. nml:namelist:: JULES_NVEGPARM + + +This namelist reads the values of parameters for each of the non-vegetation surface types if the JULES land surface model is being used. These parameters are a function of surface type only. All parameters must be defined for any configuration. + +HCTN30 refers to Hadley Centre technical note 30, available from `the Met Office Library `_. + + +.. nml:member:: albsnc_nvg_io + + :type: real(nnvg) + :default: None + + Snow-covered albedo. + + Only used if :nml:mem:`JULES_RADIATION::l_snow_albedo` = FALSE. See HCTN30 Table 1. + + +.. nml:member:: albsnf_nvg_io + + :type: real(nnvg) + :default: None + + Snow-free albedo. + + See HCTN30 Table 1. + + A bare soil snow-free albedo of -1.0 indicates that it is supplied by an ancillary field. + + +.. nml:member:: albsnf_nvgu_io + + :type: real(nnvg) + :default: None + + Upper limit on snow-free albedo, when :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE. + + +.. nml:member:: albsnf_nvgl_io + + :type: real(nnvg) + :default: None + + Lower limit on snow-free albedo, when :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE. + + +.. nml:member:: catch_nvg_io + + :type: real(nnvg) + :default: None + + Capacity for water (kg m\ :sup:`-2`). + + See HCTN30 p7. + + +.. nml:member:: gs_nvg_io + + :type: real(nnvg) + :default: None + + Surface conductance (m s\ :sup:`-1`). + + See HCTN30 p7. Soil conductance is modified by soil moisture according to HCTN30 Eq35. + + +.. nml:member:: infil_nvg_io + + :type: real(nnvg) + :default: None + + Infiltration enhancement factor. + + The maximum infiltration rate defined by the soil parameters for the whole gridbox may be modified for each surface tile to account for tile-dependent factors. + + See HCTN30 p14 for full details. + + +.. nml:member:: z0_nvg_io + + :type: real(nnvg) + :default: None + + Roughness length for momentum (m). + + See HCTN30 Table 4. + + +.. nml:member:: ch_nvg_io + + :type: real(nnvg) + :default: None + + Heat capacity of this surface type (J K\ :sup:`-1` m\ :sup:`-2`). + + Used only if :nml:mem:`JULES_VEGETATION::can_model` is 3 or 4. + + +.. nml:member:: vf_nvg_io + + :type: real(nnvg) + :default: None + + Fractional coverage of non-vegetation "canopy". + + Typically set to 0.0 (conductively coupled), but value of 1.0 (radiatively coupled) used if surface tile should have a heat capacity in conjunction with :nml:mem:`JULES_VEGETATION::can_model` options 3 or 4. + + .. note:: If :nml:mem:`JULES_URBAN::l_moruses_storage` = T, then for the roof coupling: 0 = **uncoupled** + +.. nml:member:: emis_nvg_io + + :type: real(nnvg) + :default: None + + Surface emissivity of non-vegetated surfaces. + + +.. nml:member:: z0hm_nvg_io + + :type: real(nnvg) + :default: None + + Ratio of the roughness length for heat to the roughness length for momentum. + + This is generally assumed to be 0.1. See HCTN30 p6. Note that this is the ratio of the roughness length for heat to that for momentum. It does not alter the roughness length for momentum, which is given by :nml:mem:`z0_nvg_io`. + + +.. nml:member:: z0hm_classic_nvg_io + + :type: real(nnvg) + :default: None + + Ratio of the roughness length for heat to the roughness length for momentum *for the CLASSIC aerosol scheme only*. + + .. note:: This makes no difference to the model when running standalone, and is only required to keep the standalone and UM interfaces consistent. diff --git a/doc/source/namelists/oasis_rivers.nml.rst b/doc/source/namelists/oasis_rivers.nml.rst new file mode 100644 index 00000000..591d0912 --- /dev/null +++ b/doc/source/namelists/oasis_rivers.nml.rst @@ -0,0 +1,97 @@ +``oasis_rivers.nml`` +======================= + + +This file contains a single namelists called :nml:lst:`OASIS_RIVERS`, which indicates how the Rivers-only executable couples via OASIS to other models (currently LFRIC and NEMO). This namelist is only used when running the river standalone program in coupled mode, i.e., compiling with the parameters RIVERS_ONLY and RIVER_CPL + +.. note:: This namelist is only actually used when running the Rivers-only executable (compilation flag `RIVERS_ONLY`) in coupled mode (compilation flag `RIVER_CPL`) + +``OASIS_RIVERS`` namelist members +------------------------------------ + +.. nml:namelist:: OASIS_RIVERS + +.. nml:member:: np_receive + + :type: integer + :permitted: 2 + :default: imdi + + 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. + +.. nml:member:: cpl_freq + + :type: integer + :permitted: 1: + :default: imdi + + The river coupling frequency in seconds. + +.. note:: The river coupling frequency must be a multiple of the river executable time step, and of the time steps of the models to which it is coupled. + +.. nml:member:: send_fields + + :type: character(:) + :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 (`outflow_per_river`). + +.. nml:member:: receive_fields + + :type: character(:) + :permitted: 'sub_surf_roff_rp', 'surf_roff_rp', 'sub_surf_roff', 'surf_roff' + :default: '' + + List of fields to be received by the river executable via coupling from other models. Names are case sensitive. + +.. note:: Coupled receive fields are used to substitute driving data read from file using the namelist :nml:lst:`JULES_DRIVE` by the same fields generated by a driving model running in parallel to the river executable. The only fields that can be received via coupling are the surface runoff (`surf_roff_rp`, `surf_roff`) and the sub-surface runoff (`sub_surf_roff_rp`, `sub_surf_roff`). + +.. _example_coupling_request: + +Example of coupling request +---------------------------- + +In this example, the user has requested receiving the surface and sub-surface runoffs, and sending the total river runoff via coupling. The coupling exchanges take place every hour. Please see :nml:lst:`JULES_RIVERS_PROPS` for specifying the River routing ancillary data including the river outflow number required for the calculation of 'outflow_per_river'. + +:: + + &JULES_RIVERS_PROPS + # ... + coordinate_file='$RIV_NUMBER_ANCILLARY/qrparm.rivseq.nc', + file='file_list.txt', + # ... + read_list=.true., + # ... + use_file=.true.,.true.,.true., + var='direction','sequence','rivers_outflow_number', + var_name='river_routing_direction','river_routing_sequence', + ='river_number', + # ... + / + + # ... + + &OASIS_RIVERS + cpl_freq = 3600, + np_receive = 2, + np_send = 1, + receive_fields = 'sub_surf_roff','surf_roff', + send_fields = 'outflow_per_river', + / + +:nml:mem:`JULES_RIVERS_PROPS::read_list` = TRUE indicates that the ancillary file names should be read from ``file_list.txt``, which contains for this example:: + + '$RIV_NUMBER_ANCILLARY/qrparm.rivseq.nc' + '$RIV_NUMBER_ANCILLARY/qrparm.rivseq.nc' + '$RIV_NUMBER_ANCILLARY/river_number_trip.nc' diff --git a/doc/source/namelists/output.nml.rst b/doc/source/namelists/output.nml.rst new file mode 100644 index 00000000..eda92ea4 --- /dev/null +++ b/doc/source/namelists/output.nml.rst @@ -0,0 +1,354 @@ +``output.nml`` +============== + + +This file contains a variable number of namelists that are used to specify the output required by the user. The namelist :nml:lst:`JULES_OUTPUT` should occur only once at the top of the file. The value of :nml:mem:`JULES_OUTPUT::nprofiles` in :nml:lst:`JULES_OUTPUT` then determines how many times the namelist :nml:lst:`JULES_OUTPUT_PROFILE` should appear. + + +``JULES_OUTPUT`` namelist members +--------------------------------- + +.. nml:namelist:: JULES_OUTPUT + +.. nml:member:: output_dir + + :type: character + :default: None + + The directory used for output files. This can be an absolute or relative path. + + +.. nml:member:: run_id + + :type: character + :default: None + + A name or identifier for the run. This is used to name output files and model dumps. + + +.. nml:member:: nprofiles + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of output profiles that will be specified using instances of the :nml:lst:`JULES_OUTPUT_PROFILE` namelist. + + +.. nml:member:: dump_period + + :type: integer + :permitted: >= 1 + :default: 1 + + The period between model dumps, unit depends on :nml:mem:`dump_period_unit`. + + In calendar year mode, the number of years between model dumps. Note that the calendar year (date) is used to determine whether a dump is written, not the number of years simulated so far. For example, a run that starts in the year 2012 and with :nml:mem:`dump_period` = 5 will write dumps at the start of years 2015, 2020, 2025,... + + In second of calendar day mode, the number of seconds between model dumps. Note that this is calculated using the number of seconds into the day, not the number seconds simulated so far. For example, with :nml:mem:`dump_period_unit` = 'T' and :nml:mem:`dump_period` = 10800, a run will write dumps at T00:00, T03:00, T06:00, T09:00, T12:00, T15:00, T18:00 and T21:00 of a calendar day. + + Dumps are also written at the start and end of the main run, and at the start of each cycle of any spin up. + + +.. nml:member:: dump_period_unit + + :type: character(1) + :permitted: 'Y', 'T' + :default: 'Y' + + The unit/mode for the model dump period setting :nml:mem:`dump_period`. If :nml:mem:`dump_period_unit` = 'Y', use calendar year mode (default) and :nml:mem:`dump_period` is in number of years. If :nml:mem:`dump_period_unit` = 'T', use second of calendar day mode and :nml:mem:`dump_period` is in number of seconds. + + +``JULES_OUTPUT_PROFILE`` namelist members +----------------------------------------- + +.. nml:namelist:: JULES_OUTPUT_PROFILE + +This namelist should occur :nml:mem:`JULES_OUTPUT::nprofiles` times. Each occurrence of this namelist contains information about a single output profile, as described in :doc:`/output`. + + +.. nml:member:: profile_name + + :type: character + :default: None + + The name of the output profile. + + This is used in file names and should be specified even if there is only one profile. The name for each profile should be unique to avoid overwriting data unintentionally. + + Although any name can be used for a profile, the user may wish to choose a name that reflects the variables in the file (e.g. 'carbon', 'water') or the data frequency (e.g. 'daily', 'monthly'). + + +.. nml:member:: l_land_frac + + :type: logical + :default: F + + Output gridbox land fraction to output profile. + + Required to add gribox land fraction to profile for example to + allow JULES output to drive another JULES model. + + +.. nml:member:: file_period + + :type: integer + :permitted: -3, -2, -1 or 0 + :default: 0 + + The period for output files, i.e. the time interval during which all output goes to the same file. + + .. note:: In all cases, output during spin-up goes into a separate file for each spin-up cycle and output during the main run goes into its own file(s). + + This can be one of three values: + + 0 + All output goes into the same file. + + \-1 + Monthly files are produced (i.e. all output for a month goes into the same file). + + \-2 + Annual files (calendar years) are produced. + + \-3 + Daily files are produced. + +.. nml:group:: Members used to specify the times that the profile will generate output + + .. nml:member:: output_spinup + + :type: logical + :default: F + + Determines whether the profile will provide output during model spin-up. + + TRUE + Provide output during spin-up. Output is provided for the whole of the model spin-up. Output from each spin-up cycle goes into separate files. + + FALSE + Do not provide any output during spin-up. + + + .. nml:member:: output_main_run + + :type: logical + :default: F + + Determines whether the profile will provide output during the main model run (i.e. any part of the run after spin-up). + + TRUE + Provide output during the main model run. Output will be provided for all times between :nml:mem:`output_start` and :nml:mem:`output_end` below. + + FALSE + Do not provide any output during the main model run. + + .. nml:member:: output_initial + + :type: logical + :default: F + + Determines whether the profile will output initial data for the sections for which it is outputting. + + See :ref:`initial_data` for caveats on the initial data file(s) produced. + + TRUE + Output initial data for the profile. + + If :nml:mem:`output_spinup` = T, an initial data file will be output at the start of each spinup cycle. + + If :nml:mem:`output_main_run` = T and :nml:mem:`output_start` = :nml:mem:`JULES_TIME::main_run_start`, an initial data file will be output at the start of the main run. + + FALSE + Do not output any initial data. + + .. nml:member:: output_start + .. nml:member:: output_end + + :type: character + :default: :nml:mem:`JULES_TIME::main_run_start`, :nml:mem:`JULES_TIME::main_run_end` + + The time to start and stop collecting data for output. The times that output is actually produced are determined by :nml:mem:`output_period` below. + + If :nml:mem:`output_period` is monthly, then :nml:mem:`output_start` must be 00:00:00 on the 1st of some month. + + If :nml:mem:`output_period` is yearly, then :nml:mem:`output_start` must be 00:00:00 on the 1st of January for some year. + + If :nml:mem:`output_end` is given such that an output period is not complete when the run reaches :nml:mem:`output_end`, output will not be generated for that final period (e.g. if values are being output monthly but :nml:mem:`output_end` is midday on the 31st December, then output will not be generated for December, even though most of December has been run). + + The times must be given in the format:: + + "yyyy-mm-dd hh:mm:ss" + + + .. nml:member:: output_period + + :type: integer + :permitted: -2, -1 or > 1 + :default: :nml:mem:`JULES_TIME::timestep_len` + + The period for output, in seconds. This controls the frequency with which output values are calculated; for time averages this is the length of time over which the average is calculated. + + This must be a multiple of the timestep length, except for the special cases: + + | **-1:** Monthly period + | **-2:** Annual period + + + .. nml:member:: sample_period + + :type: integer + :permitted: > 1 + :default: :nml:mem:`JULES_TIME::timestep_len` + + The sampling period, in seconds, for time-averages, minima, maxima and accumulations. + + This must be a factor of :nml:mem:`output_period` and a multiple of :nml:mem:`JULES_TIME::timestep_len`. For the 'special' cases of :nml:mem:`output_period` (e.g. monthly and annual outputs), one day must be a mutiple of :nml:mem:`sample_period`. + + :nml:mem:`output_period` controls the length of time over which any statistic (e.g. an average) is calculated; :nml:mem:`sample_period` controls how often values are sampled within that time to construct the statistic. + + .. note:: + It is strongly recommended that :nml:mem:`sample_period` be left at the default value for most applications. + + An example of when intermittent sampling can be useful is to construct a time average of values from particular timesteps, e.g. those on which a particular sub-model is called, for a variable that is reset to zero on other timesteps. Sampling every timestep will average over both the 'good' values and the zeros, whereas intermittent sampling can be used to pick up just the 'good' values. However, this is very rarely required with JULES. + + Another use for intermittent sampling is to save computational cost (at the expense of losing accuracy), though in practice this is rarely required. In exceptional cases, sampling every timestep can be relatively expensive and acceptable output can be achieved by sampling less frequently. For example, with a large domain, many output diagnostics and a timestep of 30 minutes, a monthly average would be calculated from several hundred values if every timestep was used. For variables that evolve relatively slowly, an acceptable monthly average might be obtained by sampling only every 12 hours. + + If fields are not sampled every timestep, the averages/minima/maxima/accumulations will only be approximations. + + +.. nml:group:: Members used to specify the variables that the profile will output + + .. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of variables that the profile will provide output for. + + The variables available for output are given in :doc:`/output-variables`. + + + .. nml:member:: var + + :type: character(nvars) + :default: None + + List of variable names to output, as recognised by JULES (see :doc:`/output-variables`). Names are case sensitive. + + + .. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each variable specified in :nml:mem:`var`, this is the name to give the variable in output files. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + + .. nml:member:: output_type + + :type: character(nvars) + :default: 'S' + + For each variable specified in :nml:mem:`var`, this indicates the type of processing required. + + Recognised values are: + + S + Instantaneous or snapshot value. + + M + Time mean value. + + N + Time minimum value. + + X + Time maximum value. + + A + Accumulation over time. + + For time average/minimum/maximum variables, the period over which each output value is calculated is given by :nml:mem:`output_period`. For time-accumulation variables, :nml:mem:`output_period` gives the period for output of an updated accumulation (i.e. how often the value is reported). For time averages, minima, maxima and accumulations, the sampling frequency is given by :nml:mem:`sample_period`. + + .. note:: A time-accumulation is initialised at the start of a run and thereafter accumulates until the end of the run. This may mean that accuracy is lost, particularly towards the end of long runs, if small increments are added to an already large sum. Furthermore, before being output the accumulation is multiplied by the number of model timesteps in a sample period. This adjusts the accumulation for any intermittent sampling and is designed so that the time accumulation of a flux (e.g. kg s\ :sup:`-1`) can easily be converted to a total (e.g. kg) by subsequently multiplying by the model timestep length during post processing. + + + + +Example of requesting output +---------------------------- + +In this example, the user has requested two output profiles. One provides gridbox monthly means for the whole of the main run, the other provides snapshot values of per-tile variables every timestep for a single year. We assume that :nml:mem:`JULES_TIME::timestep_len` = 1800, :nml:mem:`JULES_TIME::main_run_start` = '1995-01-01 00:00:00' and :nml:mem:`JULES_TIME::main_run_end` = '2005-01-01 00:00:00', so that exactly 10 years will be run. There is no spin-up. + +:: + + &JULES_OUTPUT + run_id = "jules_run001", + + output_dir = "./output", + + nprofiles = 2 + / + + &JULES_OUTPUT_PROFILE + profile_name = "month", + + output_main_run = T, + + output_period = -1, + + nvars = 4, + var = "emis_gb" "ftl_gb" "snow_mass_gb" "tstar_gb", + var_name = "Emissivity" "SensibleHeat" "SnowMass" "Temp", + output_type = 'M' 'M' 'M' 'M' + / + + &JULES_OUTPUT_PROFILE + profile_name = "tstep", + + output_main_run = T, + output_start = "2000-01-01 00:00:00", + output_end = "2001-01-01 00:00:00", + + nvars = 4, + var = "emis" "ftl" "snow_mass" "tstar", + output_type = 'S' 'S' 'S' 'S' + / + +Or using the alternative list syntax (see :doc:`intro`):: + + &JULES_OUTPUT + # ... as above ... + / + + &JULES_OUTPUT_PROFILE + # ... as above ... + + nvars = 4, + var(1) = "emis_gb", var_name(1) = "Emissivity", output_type(1) = 'M', + var(2) = "ftl_gb", var_name(2) = "SensibleHeat", output_type(2) = 'M', + var(3) = "snow_mass_gb", var_name(3) = "SnowMass", output_type(3) = 'M', + var(4) = "tstar_gb", var_name(4) = "Temp", output_type(4) = 'M' + / + + &JULES_OUTPUT_PROFILE + # ... as above ... + + nvars = 4, + var(1) = "emis", output_type(1) = 'S', + var(2) = "ftl", output_type(2) = 'S', + var(3) = "snow_mass", output_type(3) = 'S', + var(4) = "tstar", output_type(4) = 'S' + / + +The :nml:lst:`JULES_OUTPUT` namelist is simple - it gives an id for the run, specifies the directory to put output in and specifies the number of profile definitions that follow. + +Each profile is given a unique name. Both profiles want to output part of the main run, so must set :nml:mem:`JULES_OUTPUT_PROFILE::output_main_run` to TRUE. Since :nml:mem:`JULES_OUTPUT_PROFILE::sample_period` is not given for either profile, both will use the default (sample every timestep). The same is true for :nml:mem:`JULES_OUTPUT_PROFILE::file_period` - since it is not given for either profile, it takes its default value and all output for each profile will go into a single file. + +The first output profile wants to output monthly averages, so :nml:mem:`JULES_OUTPUT_PROFILE::output_period` is set to -1 (the special value indicating that calendar months should be used for the output period) and :nml:mem:`JULES_OUTPUT_PROFILE::output_type` is set to 'M' (for mean) for each variable. The user wants this profile to output for the whole of the main run, so does not need to specify :nml:mem:`JULES_OUTPUT_PROFILE::output_start` or :nml:mem:`JULES_OUTPUT_PROFILE::output_end` (note that this is only possible because the main run starts at 00:00:00 on the 1st of a month - if this was not the case, the user would have to specify a different time for :nml:mem:`JULES_OUTPUT_PROFILE::output_start`). The user has also chosen to supply the names that each variable will use in output files using :nml:mem:`JULES_OUTPUT_PROFILE::var_name`. + +The second output profile has specified a section of the main run that it will provide output for using :nml:mem:`JULES_OUTPUT_PROFILE::output_start` and :nml:mem:`JULES_OUTPUT_PROFILE::output_end` such that exactly a year of data will be output. Since :nml:mem:`JULES_OUTPUT_PROFILE::output_period` is not specified, it takes its default value, and output will be produced every timestep. The user has not specified the names to use in output files for this profile, so the values from :nml:mem:`JULES_OUTPUT_PROFILE::var` will be used. diff --git a/doc/source/namelists/pft_params.nml.rst b/doc/source/namelists/pft_params.nml.rst new file mode 100644 index 00000000..0c18aa84 --- /dev/null +++ b/doc/source/namelists/pft_params.nml.rst @@ -0,0 +1,1033 @@ +``pft_params.nml`` +================== + +This file sets the time and space-invariant parameters for plant functional types for the JULES land surface model. It contains one namelist called :nml:lst:`JULES_PFTPARM`. + +.. note:: + If the crop model is on (i.e. :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0), the order of PFTs must be natural PFTs followed by crop PFTs. + + +``JULES_PFTPARM`` namelist members +---------------------------------- + +.. nml:namelist:: JULES_PFTPARM + +This namelist reads the values of parameters for each of the plant functional types (PFTs) if the JULES land surface model is being used. These parameters are a function of PFT only. Parameters that also vary with time and location can be prescribed in :doc:`prescribed_data.nml`. Parameters that are only required if the dynamic vegetation (TRIFFID) or phenology sections are requested are read separately in :doc:`triffid_params.nml`. Every member must be given a value for every run. + +HCTN24 and 30 refer to Hadley Centre technical notes 24 and 30, +available from `the Met Office Library +`_. For +ease the direct links to these documents are: + +* `HCTN24 "Description of the "TRIFFID" Dynamic Global Vegetation Model" `_ +* `HCTN30 "MOSES 2.2 technical documentation" `_ + +.. nml:member:: canht_ft_io + + :type: real(npft) + :default: None + + The height of each PFT (m), also known as the canopy height. + + The value read here is only used if TRIFFID is not active (:nml:mem:`JULES_VEGETATION::l_triffid` = FALSE). + + .. note:: If TRIFFID is active, canopy height is a prognostic variable and its initial value is read in :doc:`initial_conditions.nml`. + + +.. nml:member:: lai_io + + :type: real(npft) + :default: None + + The leaf area index (LAI) of each PFT. + + The value read here is only used if neither phenology nor TRIFFID is active (:nml:mem:`JULES_VEGETATION::l_phenol` = FALSE and :nml:mem:`JULES_VEGETATION::l_triffid` = FALSE). + + .. note:: If phenology is active, LAI is a prognostic variable and its initial value is read in :doc:`initial_conditions.nml`. When TRIFFID is active but phenology is not active (not recommended), LAI is calculated from the canopy height (meaning that the seasonal cycle of LAI will not be correctly represented). + + +.. nml:member:: c3_io + + :type: integer(npft) + :default: None + + Flag indicating whether PFT is C3 type. + + 0. Not C3 (i.e. C4). + + 1. C3. + + +.. nml:member:: orient_io + + :type: integer(npft) + :default: None + + Flag indicating leaf angle distribution. + + 0. Spherical. + + 1. Horizontal. + + +.. nml:member:: can_struct_a_io + + :type: real(npft) + :default: None + + Canopy structure factor (dimensionless). can_struct_a_io=1.0 indicates a structurally homogeneous canopy. Corresponds to the structure factor Zeta in Pinty et al 2006 except assumed not to vary with zenith angle i.e. b=0. The canopy structure factor has no effect if :nml:mem:`JULES_VEGETATION::can_rad_mod` = 1. + +.. nml:member:: a_wl_io + + :type: real(npft) + :default: None + + Allometric coefficient relating the target woody biomass to the + leaf area index (kg carbon m\ :sup:`-2`) (Clark et al., 2011; Table 7) + + +.. nml:member:: a_ws_io + + :type: real(npft) + :default: None + + Woody biomass as a multiple of live stem biomass (Clark et al., 2011; Table 7). + + +.. nml:member:: albsnc_max_io + + :type: real(npft) + :default: None + + Snow-covered albedo for large leaf area index. + + Only used if :nml:mem:`JULES_RADIATION::l_snow_albedo` = FALSE. See HCTN30 Eq.2. + + +.. nml:member:: albsnc_min_io + + :type: real(npft) + :default: None + + Snow-covered albedo for zero leaf area index. + + Only used if :nml:mem:`JULES_RADIATION::l_snow_albedo` = FALSE. See HCTN30 Eq.2. + + +.. nml:member:: albsnf_max_io + + :type: real(npft) + :default: None + + Snow-free albedo for large LAI. + + Only used if :nml:mem:`JULES_RADIATION::l_spec_albedo` = FALSE. See HCTN30 Eq.1. + + +.. nml:member:: albsnf_maxu_io + + :type: real(npft) + :default: None + + Upper bound for the snow-free albedo for large LAI, when scaled to match input obs. + + Only used if :nml:mem:`JULES_RADIATION::l_spec_albedo` = FALSE and :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE. + + +.. nml:member:: albsnf_maxl_io + + :type: real(npft) + :default: None + + Lower bound for the snow-free albedo for large LAI, when scaled to match input obs. + + Only used if :nml:mem:`JULES_RADIATION::l_spec_albedo` = FALSE and :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE. + + +.. nml:member:: alpha_io + + :type: real(npft) + :default: None + + Quantum efficiency of photosynthesis (mol CO\ :sub:`2` per mol PAR photons). + + +.. nml:member:: alnir_io + + :type: real(npft) + :default: None + + Leaf reflection coefficient for NIR. See HCTN30 Table 3. + + Always used unless :nml:mem:`JULES_VEGETATION::can_rad_mod` = 1 and + :nml:mem:`JULES_RADIATION::l_spec_albedo` = FALSE. + + +.. nml:member:: alniru_io + + :type: real(npft) + :default: None + + Upper limit for the leaf reflection coefficient for NIR, when + :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE and when + :nml:mem:`alnir_io` is used. + + +.. nml:member:: alnirl_io + + :type: real(npft) + :default: None + + Lower limit for the leaf reflection coefficient for NIR, when + :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE and when + :nml:mem:`alnir_io` is used. + + +.. nml:member:: alpar_io + + :type: real(npft) + :default: None + + Leaf reflection coefficient for VIS (photosyntehtically active radiation). See HCTN30 Table 3. + + Always used unless :nml:mem:`JULES_VEGETATION::can_rad_mod` = 1 and + :nml:mem:`JULES_RADIATION::l_spec_albedo` = FALSE. + + +.. nml:member:: alparu_io + + :type: real(npft) + :default: None + + Upper limit for the leaf reflection coefficient for VIS, when + :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE and when + :nml:mem:`alpar_io` is used. + + +.. nml:member:: alparl_io + + :type: real(npft) + :default: None + + Lower limit for the leaf reflection coefficient for VIS, when + :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE and when + :nml:mem:`alpar_io` is used. + + +.. nml:member:: b_wl_io + + :type: real(npft) + :default: None + + Allometric exponent relating the target woody biomass to the leaf + area index. This is 5/3 in HCTN24 Eq.8. See also Clark et + al. (2011, Table 7). + + +.. nml:member:: catch0_io + + :type: real(npft) + :default: None + + Minimum canopy capacity (kg m\ :sup:`-2`). + + This is the minimum amount of water that can be held on the canopy. See HCTN30 p7. + + +.. nml:member:: dcatch_dlai_io + + :type: real(npft) + :default: None + + Rate of change of canopy capacity with LAI (kg m\ :sup:`-2`). + + Canopy capacity is calculated as ``catch0 + dcatch_dlai*lai``. See HCTN30 p7. + + +.. nml:member:: dgl_dm_io + + :type: real(npft) + :default: None + + Rate of change of leaf turnover rate with moisture availability. + + +.. nml:member:: dgl_dt_io + + :type: real(npft) + :default: None + + Rate of change of leaf turnover rate with temperature (K\ :sup:`-1`). + + This is 9 in HCTN24 Eq.10. + + +.. nml:member:: dqcrit_io + + :type: real(npft) + :default: None + + Critical humidity deficit (kg H\ :sub:`2`\ O per kg air). + + Only used with the Jacobs model of stomatal conductance (:nml:mem:`JULES_VEGETATION::stomata_model` = 1). + + +.. nml:member:: dz0v_dh_io + + :type: real(npft) + :default: None + + Rate of change of vegetation roughness length for momentum with height. + + Roughness length is calculated as ``dz0v_dh * canht_ft``. See HCTN30 p5. + + Used if logical :nml:mem:`JULES_VEGETATION::l_spec_veg_z0` is set to .false. + +.. nml:member:: z0v_io + + :type: real(npft) + :default: None + + Specified values for the vegetation roughness length for momentum. + + Used if logical :nml:mem:`JULES_VEGETATION::l_spec_veg_z0` is set to .true. + + +.. nml:member:: eta_sl_io + + :type: real(npft) + :default: None + + Live stemwood coefficient (kg C/m/(m2 leaf)) (Clark et al., 2011; Table 7). + + +.. nml:member:: fd_io + + :type: real(npft) + :default: None + + Scale factor for dark respiration. See HCTN 24 Eq. 56. + + +.. nml:member:: fsmc_of_io + + :type: real(npft) + :default: None + + Moisture availability below which leaves are dropped. + + +.. nml:member:: f0_io + + :type: real(npft) + :default: None + + ``CI / CA`` for ``DQ = 0``. See HCTN 24 Eq. 32. + + Only used with the Jacobs model of stomatal conductance (:nml:mem:`JULES_VEGETATION::stomata_model` = 1). + + +.. nml:member:: g1_stomata_io + + :type: real(npft) + :default: None + + Parameter g1 for the Medlyn et al. (2011) model of stomatal conductance (kPa\ :sup:`0.5`) - this is the sensitivity of the stomatal conductance to the assimilation rate. See Eqn.11 in Medlyn et al. (2012), https://doi.org/10.1111/j.1365-2486.2012.02790.x. + + 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) + :default: None + + Minimum turnover rate for leaves (/360days). + + +.. nml:member:: glmin_io + + :type: real(npft) + :default: None + + Minimum leaf conductance for H\ :sub:`2`\ O (m s\ :sup:`-1`). + + +.. nml:member:: infil_f_io + + :type: real(npft) + :default: None + + Infiltration enhancement factor. + + The maximum infiltration rate defined by the soil parameters for the whole gridbox may be modified for each PFT to account for PFT-dependent factors, such as macro-pores related to vegetation roots. + + See HCTN30 p14 for full details. + +.. nml:member:: gsoil_f_io + + :type: real(npft) + :default: None + + Soil conductance enhancement factor. + + The soil conductance for soil under a PFT canopy may be modified for each PFT (as compared to the bare soil conductance) to account for PFT-dependent factors. + +.. nml:member:: hw_sw_io + + :type: real(npft) + :default: None + + Ratio of N stem to N heartwood (kgN/kgN) from the TRY database. + + Only used if :nml:mem:`JULES_VEGETATION::l_trait_phys` = T. + + +.. nml:member:: kext_io + + :type: real(npft) + :default: None + + Light extinction coefficient - used with Beer's Law for light absorption through plant canopies. See HCTN30 Eq.3. + + +.. nml:member:: kpar_io + + :type: real(npft) + :default: None + + PAR Extinction coefficient (m\ :sup:`2` leaf / m\ :sup:`2` ground). + + +.. nml:member:: lai_alb_lim_io + + :type: real(npft) + :default: None + + Minimum LAI in calculation of albedo in the absence of snow. + + A minimum LAI is imposed when calculating the albedo of plant + canopies (historically 0.5). This parameter allows it to be set + for each PFT in the absence of snow. Crudely, it represents the + stem area of vegetation remaining when the true LAI is 0. A + separate variable, :nml:mem:`JULES_SNOW::lai_alb_lim_sn` is + used in the presence of snow. + + +.. nml:member:: neff_io + + :type: real(npft) + :default: None + + Scale factor relating V\ :sub:`cmax` with leaf nitrogen concentration. See HCTN 24 Eq. 51. + + Only used if :nml:mem:`JULES_VEGETATION::l_trait_phys` = F. + + +.. nml:member:: nl0_io + + :type: real(npft) + :default: None + + Top leaf nitrogen concentration (kg N/kg C). + + Only used if :nml:mem:`JULES_VEGETATION::l_trait_phys` = F. + + +.. nml:member:: nr_nl_io + + :type: real(npft) + :default: None + + Ratio of root nitrogen concentration to leaf nitrogen concentration. + +.. nml:member:: nr_io + + :type: real(npft) + :default: None + + Root nitrogen concentration (kgN/kgC). + Only used if :nml:mem:`JULES_VEGETATION::l_trait_phys` = T. + +.. nml:member:: ns_nl_io + + :type: real(npft) + :default: None + + Ratio of stem nitrogen concentration to leaf nitrogen concentration. + +.. nml:member:: nsw_io + + :type: real(npft) + :default: None + + Stemwood nitrogen concentration (kgN/kgC). + Only used if :nml:mem:`JULES_VEGETATION::l_trait_phys` = T. + +.. nml:member:: hw_sw_io + + :type: real(npft) + :default: None + + Ratio of Heartwood to Stemwood Nitrogen Concentration (typically 0.5) + Only used if :nml:mem:`JULES_VEGETATION::l_trait_phys` = T. + +.. nml:member:: omega_io + + :type: real(npft) + :default: None + + Leaf scattering coefficient for PAR. + + Always used unless :nml:mem:`JULES_VEGETATION::can_rad_mod` = 1 and + :nml:mem:`JULES_RADIATION::l_spec_albedo` = FALSE. + + +.. nml:member:: omegau_io + + :type: real(npft) + :default: None + + Upper limit for the leaf scattering coefficient for PAR, when + :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE and when + :nml:mem:`omega_io` is used. + + +.. nml:member:: omegal_io + + :type: real(npft) + :default: None + + Lower limit for the leaf scattering coefficient for PAR, when + :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE and when + :nml:mem:`omega_io` is used. + + +.. nml:member:: omnir_io + + :type: real(npft) + :default: None + + Leaf scattering coefficient for NIR. + + Always used unless :nml:mem:`JULES_VEGETATION::can_rad_mod` = 1 and + :nml:mem:`JULES_RADIATION::l_spec_albedo` = FALSE. + + +.. nml:member:: omniru_io + + :type: real(npft) + :default: None + + Upper limit for the leaf scattering coefficient for NIR, when + :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE and when + :nml:mem:`omnir_io` is used. + + +.. nml:member:: omnirl_io + + :type: real(npft) + :default: None + + Lower limit for the leaf scattering coefficient for NIR, when + :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE and when + :nml:mem:`omnir_io` is used. + + +.. nml:member:: r_grow_io + + :type: real(npft) + :default: None + + Growth respiration fraction. + + +.. nml:member:: fsmc_mod_io + + :type: integer(npft) + :default: None + + Switch for method of weighting the contribution that different soil layers make to the soil moisture availability factor fsmc. + + 0. (recommended) Calculate fsmc in each soil layer and take a weighted average, using the fraction of roots in each layer as weights. Root distribution e-folding depth is given by :nml:mem:`rootd_ft_io`. + + 1. Calculate fsmc using average properties for the root zone. Depth of root zone is given by :nml:mem:`rootd_ft_io`. This is not currently allowed if layered soil C (:nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = TRUE) and the 4-pool model are selected (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2) because of unplanned effects on litter inputs. + + +.. nml:member:: psi_open_io + + :type: real(npft) + :default: None + + Soil potential above which the soil moisture stress factor on vegetation (fsmc) is one. Unit: Pa. Allowed range: must be negative. Only used if :nml:mem:`JULES_VEGETATION::l_use_pft_psi` = T. + + +.. nml:member:: psi_close_io + + :type: real(npft) + :default: None + + Soil potential below which the soil moisture stress factor on vegetation (fsmc) is zero. Unit: Pa. Allowed range: must be negative. Only used if :nml:mem:`JULES_VEGETATION::l_use_pft_psi` = T. + + +.. nml:member:: rootd_ft_io + + :type: real(npft) + :default: None + + Parameter determining the root depth (m). + + If :nml:mem:`fsmc_mod_io` = 0, an exponential root distribution with depth is assumed, with e-folding depth ``rootd_ft`` (see HCTN30 Eq.32). Note that this means that generally some of the roots exist at depths greater than ``rootd_ft``. If :nml:mem:`fsmc_mod_io` = 1, ``rootd_ft`` is the total depth of the root zone. + + +.. nml:member:: fsmc_p0_io + + :type: real(npft) + :default: None + + Pft-dependent parameter governing the threshold at which the plant starts to experience water stress due to lack of water in the soil. Only used if :nml:mem:`JULES_VEGETATION::l_use_pft_psi` = F. The volumetric soil moisture content (m\ :sup:`3` water per m\ :sup:`3` soil) at which the plant starts to become water stressed is ``sm_wilt+(sm_crit-sm_wilt)*(1-fsmc_p0)`` (see :nml:lst:`JULES_SOIL_PROPS` for a description of ``sm_wilt`` and ``sm_crit``). + + +.. nml:member:: sigl_io + + :type: real(npft) + :default: None + + Specific density of leaf carbon (kg C/m\ :sup:`2` leaf) (Clark et al., 2011; Table 7). + + Only used if :nml:mem:`JULES_VEGETATION::l_trait_phys` = F. + + +.. nml:member:: tleaf_of_io + + :type: real(npft) + :default: None + + Temperature below which leaves are dropped (K). + + +.. nml:member:: tlow_io + + :type: real(npft) + :default: None + + Lower temperature parameter for photosynthesis (deg C), for the Collatz model of leaf photosynthesis. + + Always used for C\ :sub:`4` plants. Only used for C\ :sub:`3` plants with the Collatz model of leaf photosynthesis (:nml:mem:`JULES_VEGETATION::photo_model` = 1). + + +.. nml:member:: tupp_io + + :type: real(npft) + :default: None + + Upper temperature parameter for photosynthesis (deg C), for the Collatz model of leaf photosynthesis. + + Always used for C\ :sub:`4` plants. Only used for C\ :sub:`3` plants with the Collatz model of leaf photosynthesis (:nml:mem:`JULES_VEGETATION::photo_model` = 1). + + +.. nml:member:: emis_pft_io + + :type: real(npft) + :default: None + + Surface emissivity of vegetated surfaces. + + +.. nml:member:: z0hm_pft_io + + :type: real(npft) + :default: None + + Ratio of the roughness length for heat to the roughness length for momentum. + + This is generally assumed to be 0.1. See HCTN30 p6. Note that this is the ratio of the roughness length for heat to that for momentum. It does not alter the roughness length for momentum, which is calculated using :nml:mem:`canht_ft_io` and :nml:mem:`dz0v_dh_io`. + + +.. nml:member:: z0hm_classic_pft_io + + :type: real(npft) + :default: None + + Ratio of the roughness length for heat to the roughness length for momentum *for the CLASSIC aerosol scheme only*. + + .. note:: This makes no difference to the model when running standalone, and is only required to keep the standalone and UM interfaces consistent. + + +.. nml:member:: fl_o3_ct_io + + :type: real(npft) + :default: None + + Critical flux of O3 to vegetation (nmol m\ :sup:`-2` s\ :sup:`-1`). + + +.. nml:member:: dfp_dcuo_io + + :type: real(npft) + :default: None + + Plant type specific O3 sensitivity parameter (nmol\ :sup:`-1` m\ :sup:`2` s). + + +.. nml:member:: ief_io + + :type: real(npft) + :default: None + + Isoprene Emission Factor (\ |mu|\ g g\ :sup:`-1` h\ :sup:`-1`). + + +.. nml:member:: tef_io + + :type: real(npft) + :default: None + + Monoterpene Emission Factor (\ |mu|\ g g\ :sup:`-1` h\ :sup:`-1`). + + +.. nml:member:: mef_io + + :type: real(npft) + :default: None + + Methanol Emission Factor (\ |mu|\ g g\ :sup:`-1` h\ :sup:`-1`). + + +.. nml:member:: aef_io + + :type: real(npft) + :default: None + + Acetone Emission Factor (\ |mu|\ g g\ :sup:`-1` h\ :sup:`-1`). + + +.. nml:member:: ci_st_io + + :tybe: real(npft) + :default: None + + Leaf-internal CO\ :sub:`2`\ concentration at standard conditions (Pa), + + .. note:: Standard conditions are: T = 303.15K, p = 1013.25 hPa, atmospheric CO\ :sub:`2` = 370 ppmv, PAR = 1000 \ |mu|\ mol m\ :sup:`-2` s\ :sup:`-1`. + + +.. nml:member:: gpp_st_io + + :tybe: real(npft) + :default: None + + Gross primary production (GPP) at standard conditions (kgC m\ :sup:`-2` s\ :sup:`-1`), + + .. note:: Standard conditions are: T = 303.15K, p = 1013.25 hPa, atmospheric CO\ :sub:`2` = 370 ppmv, PAR = 1000 \ |mu|\ mol m\ :sup:`-2` s\ :sup:`-1`. + + +.. nml:member:: nmass_io + + :type: real(npft) + :default: None + + Top leaf nitrogen content per unit mass (kgN kgLeaf\ :sup:`-1`). + + Only used if :nml:mem:`JULES_VEGETATION::l_trait_phys` = T. + + +.. nml:member:: lma_io + + :type: real(npft) + :default: None + + Leaf mass per unit area (kgLeaf m\ :sup:`-2`). + + Only used if :nml:mem:`JULES_VEGETATION::l_trait_phys` = T. + + +.. nml:member:: vint_io + + :type: real(npft) + :default: None + + There is a linear relationship between Vcmax and Narea. Previously Vcmax was calculated as the product of nl0 and neff. + + This is now replaced by a linear regression based on data reported in Kattge et al. 2009. Vint is the y-intercept, vsl is the slope. + + Units: \ |mu|\ mol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`. + + Only used if :nml:mem:`JULES_VEGETATION::l_trait_phys` = T. + + +.. nml:member:: vsl_io + + :type: real(npft) + :default: None + + Slope in the linear regression between Vcmax and Narea. + + Units: \ |mu|\ mol CO\ :sub:`2` gN\ :sup:`-1` s\ :sup:`-1`. + + Only used if :nml:mem:`JULES_VEGETATION::l_trait_phys` = T. + + +.. nml:member:: kn_io + + :type: real(npft) + :default: None. + + Parameter for decay of nitrogen through the canopy, as a function of layers. Only used if :nml:mem:`JULES_VEGETATION::can_rad_mod` = 4 or 5. + + +.. nml:member:: knl_io + + :type: real(npft) + :default: None. + + Parameter for decay of nitrogen through the canopy, as a function of LAI. Only used if :nml:mem:`JULES_VEGETATION::can_rad_mod` = 6. + + +.. nml:member:: q10_leaf_io + + :type: real(npft) + :default: None. + + Q10 factor for plant respiration. + + See Cox et al. (1999) Eq. 66. + + .. note:: Was previously a single parameter but now can have PFT-dependent values. + + +.. nml:member:: fef_co2_io + + :type: real(npft) + :default: None + + Fire CO\ :sub:`2` Emission Factor (g kg\ :sup:`-1`). + +.. nml:member:: fef_co_io + + :type: real(npft) + :default: None + + Fire CO Emission Factor (g kg\ :sup:`-1`). + +.. nml:member:: fef_ch4_io + + :type: real(npft) + :default: None + + Fire CH\ :sub:`4` Emission Factor (g kg\ :sup:`-1`). + +.. nml:member:: fef_nox_io + + :type: real(npft) + :default: None + + Fire NOx Emission Factor (g kg\ :sup:`-1`). + +.. nml:member:: fef_so2_io + + :type: real(npft) + :default: None + + Fire SO\ :sub:`2` Emission Factor (g kg\ :sup:`-1`). + +.. nml:member:: fef_oc_io + + :type: real(npft) + :default: None + + Fire OC Emission Factor (g kg\ :sup:`-1`). + +.. nml:member:: fef_bc_io + + :type: real(npft) + :default: None + + Fire BC Emission Factor (g kg\ :sup:`-1`). + +.. nml:member:: ccleaf_min_io + + :type: real(npft) + :default: None + + Leaf minimum combustion completeness. + +.. nml:member:: ccleaf_max_io + + :type: real(npft) + :default: None + + Leaf maximum combustion completeness. + +.. nml:member:: ccwood_min_io + + :type: real(npft) + :default: None + + Wood minimum combustion completeness. + +.. nml:member:: ccwood_max_io + + :type: real(npft) + :default: None + + Wood maximum combustion completeness. + +.. nml:member:: avg_ba_io + + :type: real(npft) + :default: None + + Average PFT Burnt Area per fire (m\ :sup:`2`). + +.. nml:member:: fire_mort_io + + :type: real(npft) + :default: None + + Scaling factor for vegetation mortality caused by fire (from INFERNO burned area). Can be varied between 0.0 (no morality) and 1.0 (100% mortality) for each PFT. + + .. seealso:: + References: + + * Clark et al., 2011, The Joint UK Land Environment Simulator + (JULES), model description – Part 2: Carbon fluxes and + vegetation dynamics, Geosci. Model Dev., 4, 701-722, + https://doi.org/10.5194/gmd-4-701-2011 + * Pinty, B., T. Lavergne, R. E. Dickinson, + J.-L. Widlowski, N. Gobron, and M. M. Verstraete (2006), + Simplifying the interaction of land surfaces with radiation + for relating remote sensing products to climate + models, J. Geophys. Res., 111, D02116, + https://doi.org/10.1029/2005JD005952. + + + + + +.. nml:group:: Only used with the Farquhar model of leaf photosynthesis (:nml:mem:`JULES_VEGETATION::photo_model` = 2). A value is required for each PFT, but only those for C\ :sub:`3` plants are used (since only C\ :sub:`3` plants use the Farquhar model). Below, J\ :sub:`max` is the potential rate of electron transport, and V\ :sub:`cmax` is the maximum rate of carboxylation of Rubisco. + + + .. nml:member:: act_jmax_io + + :type: real(npft) + :default: None + + Activation energy for temperature response of J\ :sub:`max` (J mol\ :sup:`-1`). + + + .. nml:member:: act_vcmax_io + + :type: real(npft) + :default: None + + Activation energy for temperature response of V\ :sub:`cmax` (J mol\ :sup:`-1`). + + .. note:: + :nml:mem:`act_jmax_io` and :nml:mem:`act_vcmax_io` are NOT required if thermal adaptation or acclimation of photosynthesis is selected (:nml:mem:`JULES_VEGETATION::photo_acclim_model` = 1, 2 or 3) together with :nml:mem:`JULES_VEGETATION::photo_act_model` = 2. + + + .. nml:member:: alpha_elec_io + + :type: real(npft) + :default: None + + Quantum yield of electron transport (mol electrons [mol\ :sup:`-1` PAR photons]). + + + .. nml:member:: deact_jmax_io + + :type: real(npft) + :default: None + + Deactivation energy for temperature response of J\ :sub:`max` (J mol\ :sup:`-1`). This describes the rate of decrease above the optimum temperature. + + + .. nml:member:: deact_vcmax_io + + :type: real(npft) + :default: None + + Deactivation energy for temperature response of V\ :sub:`cmax` (J mol\ :sup:`-1`). This describes the rate of decrease above the optimum temperature. + + + .. nml:member:: jv25_ratio_io + + :type: real(npft) + :default: None + + Ratio of J\ :sub:`max` to V\ :sub:`cmax` at 25 deg C (mol electrons [mol\ :sup:`-1` CO\ :sub:`2`]). + + .. note:: + If thermal adaptation or acclimation of photosynthesis is selected (:nml:mem:`JULES_VEGETATION::photo_acclim_model` = 1 or 2) together with :nml:mem:`JULES_VEGETATION::photo_jv_model` =2 (J\ :sub:`max`/V\ :sub:`cmax` calculated assuming constant total nitrogen allocation)), this value is used along with parameters :nml:mem:`JULES_VEGETATION::n_alloc_jmax` and :nml:mem:`JULES_VEGETATION::n_alloc_vcmax` to calculate the final value of J\ :sub:`max`/V\ :sub:`cmax`. + + +.. nml:group:: Only used if thermal adaptation or acclimation of photosynthetic capacity is NOT modelled (:nml:mem:`JULES_VEGETATION::photo_acclim_model` = 0). A value is required for each PFT, but only those for C\ :sub:`3` plants are used (since only C\ :sub:`3` plants use the Farquhar model). + + + .. nml:member:: ds_jmax_io + + :type: real(npft) + :default: None + + Entropy factor for temperature reponse of J\ :sub:`max` (J mol\ :sup:`-1` K\ :sup:`-1`). + + + .. nml:member:: ds_vcmax_io + + :type: real(npft) + :default: None + + Entropy factor for temperature reponse of V\ :sub:`cmax` (J mol\ :sup:`-1` K\ :sup:`-1`). + +.. nml:group:: Only used if the respiration is modelled using the SUGAR carbohydrate model (:nml:mem:`JULES_VEGETATION::l_sugar` = T). A value is required for each PFT. + + + .. nml:member:: sug_grec_io + + :type: real(npft) + :default: None + + Specific structural carbon recycling rate (kg carbon m\ :sup:`-2` s\ :sup:`-1`). + + + .. nml:member:: sug_g0_io + + :type: real(npft) + :default: None + + Specific structural carbon production rate (kg carbon m\ :sup:`-2` s\ :sup:`-1`). + + .. nml:member:: sug_yg_io + + :type: real(npft) + :default: None + + Growth yield for SUGAR model + +.. |mu| unicode:: μ .. u diff --git a/doc/source/namelists/prescribed_data.nml.rst b/doc/source/namelists/prescribed_data.nml.rst new file mode 100644 index 00000000..3118ab6d --- /dev/null +++ b/doc/source/namelists/prescribed_data.nml.rst @@ -0,0 +1,288 @@ +``prescribed_data.nml`` +======================= + + +This file contains a variable number of namelists that are used to prescribe time-varying input data that is not meteorological forcing. The namelist :nml:lst:`JULES_PRESCRIBED` should occur only once at the top of the file. The value of :nml:mem:`JULES_PRESCRIBED::n_datasets` in :nml:lst:`JULES_PRESCRIBED` then determines how many times the namelist :nml:lst:`JULES_PRESCRIBED_DATASET` should occur. + + +``JULES_PRESCRIBED`` namelist members +------------------------------------- + +.. nml:namelist:: JULES_PRESCRIBED + + +.. nml:member:: n_datasets + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of datasets that will be specified using instances of the :nml:lst:`JULES_PRESCRIBED_DATASET` namelist. + + + +``JULES_PRESCRIBED_DATASET`` namelist members +--------------------------------------------- + +.. nml:namelist:: JULES_PRESCRIBED_DATASET + +This namelist should occur :nml:mem:`JULES_PRESCRIBED::n_datasets` times. Each occurrence of this namelist contains information about a single dataset (i.e. set of related files). + + +.. nml:group:: Members used to specify the start, end and period of the data + + .. nml:member:: data_start + .. nml:member:: data_end + + :type: character + :default: None + + The times of the start of the first timestep of data and the end of the last timestep of data. + + Each run of JULES (configured in :doc:`timesteps.nml`) can use part or all of the specified data. However, there must be data for all times between run start and run end (determined by :nml:mem:`JULES_TIME::main_run_start`, :nml:mem:`JULES_TIME::main_run_end`, :nml:mem:`JULES_SPINUP::spinup_start` and :nml:mem:`JULES_SPINUP::spinup_end`). + + The times must be given in the format:: + + "yyyy-mm-dd hh:mm:ss" + + + .. nml:member:: data_period + + :type: integer + :permitted: -2, -1 or > 0 + :default: None + + The period, in seconds, of the data. + + Special cases: + + | **-1:** Monthly data + | **-2:** Yearly data + + + .. nml:member:: is_climatology + + :type: logical + :default: F + + Indicates whether the data is to be used as a climatology (use the same data for every year). + + TRUE + Interpret the data as a climatology. :nml:mem:`data_start` and :nml:mem:`data_end` must be such that exactly one year of data is specified. + + FALSE + Do not interpret the data as a climatology. + + +.. nml:group:: Members used to specify the files containing the data + + .. nml:member:: read_list + + :type: logical + :default: F + + Switch controlling how data file names are determined for a given time. + + TRUE + Use a list of data file names with times of first data. + + FALSE + Use a single data file for all times or a template describing the names of the data files. + + + .. nml:member:: nfiles + + :type: integer + :permitted: >= 0 + :default: 0 + + Only used if :nml:mem:`read_list` = TRUE. + + The number of data files to read name and time of first data for. + + + .. nml:member:: file + + :type: character + :default: None + + If :nml:mem:`read_list` = TRUE, this is the file to read the list of data file names and times from. Each line should be of the form:: + + '/data/file', 'yyyy-mm-dd hh:mm:ss' + + In this case data file names may contain variable name templating only, with the proviso that either no file names use variable name templating or all file names do. The files must appear in chronological order. + + If :nml:mem:`read_list` = FALSE, this is either the single data file (if no templating is used) or a template for data file names. Both :doc:`time and variable name templating ` may be used. + + +.. nml:group:: Members used to specify the provided variables + + .. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + The number of variables that the dataset will provide. + + See :ref:`supported-prescribed-variables` for the supported variables. + + + .. nml:member:: var + + :type: character(nvars) + :default: None + + List of variable names as recognised by JULES (see :ref:`supported-prescribed-variables`). Names are case sensitive. + + .. note:: For ASCII files, variable names must be in the order they appear in the file. + + + .. nml:member:: var_name + + :type: character(nvars) + :default: '' (empty string) + + For each JULES variable specified in :nml:mem:`var`, this is the name of the variable in the file(s) containing the data. + + If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. + + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. + + + .. nml:member:: tpl_name + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name(s) in place of the variable name substitution string. + + If the file name(s) do not use variable name templating, this is not used. + + + .. nml:member:: interp + + :type: character(nvars) + :default: None + + For each JULES variable specified in :nml:mem:`var`, this indicates how the variable is to be interpolated in time (see :doc:`/input/temporal-interpolation`). + + + .. nml:member:: prescribed_levels + + :type: integer(n) where n ranges from 1 (one level prescribed) to :nml:mem:`JULES_SOIL::sm_levels` (all levels prescribed) + :default: 1, ..., :nml:mem:`JULES_SOIL::sm_levels` i.e. all levels prescribed + + Indices of the subset of levels to be prescribed. Currently only implemented for :nml:mem:`var` = ``sthuf`` and :nml:mem:`nvars` = 1. The numbering of the soil level indices starts at 1 (corresponding to the layer touching the surface). Note that ``sthuf`` data must be provided for all soil levels, but can be set to dummy values for the levels that are not prescribed. + + +.. _supported-prescribed-variables: + +List of supported variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All variables input using :doc:`prescribed_data.nml` must have a time dimension using :nml:mem:`JULES_INPUT_GRID::time_dim_name`. + +In theory, any variable with an entry in the subroutine ``populate_var`` in ``model_interface_mod`` (see :doc:`/code/io`) can be updated via this mechanism, and the use of any of these variables is not explicitly prevented. However, it is up to the user to assess whether using this mechanism to update any particular variable is appropriate or desirable. + +The use of the following variables is explicitly supported: + +.. tabularcolumns:: |p{2.5cm}|p{8cm}|p{4cm}| + ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| Name | Description | Levels dimension(s) required in files | ++===========================+===================================================================+===================================================+ +| ``ozone`` | Surface ozone concentration (ppb). | None | +| | | | +| | .. note:: | | +| | Required if :nml:mem:`JULES_VEGETATION::l_o3_damage` = TRUE. | | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``canht`` | PFT canopy height (m). | Single levels dimension of size | +| | | :nml:mem:`JULES_SURFACE_TYPES::npft` using | +| | .. note:: | :nml:mem:`JULES_INPUT_GRID::pft_dim_name`. | +| | Not possible if :nml:mem:`JULES_VEGETATION::l_triffid` = TRUE | | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``lai`` | PFT leaf area index. | Single levels dimension of size | +| | | :nml:mem:`JULES_SURFACE_TYPES::npft` using | +| | .. note:: | :nml:mem:`JULES_INPUT_GRID::pft_dim_name`. | +| | Not possible if :nml:mem:`JULES_VEGETATION::l_triffid` = TRUE | | +| | or :nml:mem:`JULES_VEGETATION::l_phenol` = TRUE | | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``albobs_sw`` | Observed SW diffuse albedo. | None | +| | | | +| | .. note:: | | +| | Required if :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE and | | +| | :nml:mem:`JULES_RADIATION::l_spec_albedo` = FALSE. | | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``albobs_vis`` | Observed VIS diffuse albedo. | None | +| | | | +| | .. note:: | | +| | Required if :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE and | | +| | :nml:mem:`JULES_RADIATION::l_spec_albedo` = TRUE. | | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``albobs_nir`` | Observed NIR diffuse albedo. | None | +| | | | +| | .. note:: | | +| | Required if :nml:mem:`JULES_RADIATION::l_albedo_obs` = TRUE and | | +| | :nml:mem:`JULES_RADIATION::l_spec_albedo` = TRUE. | | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``co2_mmr`` | Concentration of atmospheric CO2, expressed as a mass mixing | None | +| | ratio. | | +| | | | +| | .. note:: | | +| | A single value of co2_mmr is applied globally. Data must be | | +| | supplied for each gridpoint, but only the value of the first | | +| | grid-point is used. | | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``sthuf`` | Soil wetness for each soil layer. This is the mass of soil water | Single levels dimension of size | +| | (liquid and frozen), expressed as a fraction of the water | :nml:mem:`JULES_SOIL::sm_levels` using | +| | content at saturation. | :nml:mem:`JULES_INPUT_GRID::soil_dim_name`. | +| | | | +| | .. note:: | | +| | Soil wetness will be set to the prescribed value at the | | +| | beginning of each timestep but will be incremented during | | +| | that timestep. Also, it is recommended that the prescribed | | +| | ``sthuf`` does not exceed one. | | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``frac_agr`` | Fractional area of agricultural land in each gridbox. | None | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``frac_past`` | Fractional area of pasture land in each gridbox. | None | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``frac_biocrop`` | Fractional area of bioenergy cropland in each gridbox. | None | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``tracer_field`` | Surface concentration of atmospheric chemical tracers in the | Single levels dimension of size | +| | atmosphere, for calculation of deposition, as mass mixing ratio | :nml:mem:`JULES_DEPOSITION::ndry_dep_species` | +| | (kg kg :sup:`-1`). | using | +| | | :nml:mem:`JULES_INPUT_GRID::tracer_dim_name`. | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``bl_height`` | Height above surface of top of atmospheric boundary layer (m). | None | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``level_separation`` | Separation of boundary layer levels (m). | Single levels dimension of size | +| | The levels are listed starting at the surface and working up. | :nml:mem:`JULES_NLSIZES::bl_levels` using | +| | | :nml:mem:`JULES_INPUT_GRID::bl_level_dim_name`. | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``demand_rate_domestic`` | Demand for water for domestic use (kg s :sup:`-1`) | None | +| | | | +| | .. note:: | | +| | Required if :nml:mem:`JULES_WATER_RESOURCES::l_water_domestic` | | +| | = TRUE. | | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``demand_rate_industry`` | Demand for water for industrial use (kg s :sup:`-1`) | None | +| | | | +| | .. note:: | | +| | Required if :nml:mem:`JULES_WATER_RESOURCES::l_water_industry` | | +| | = TRUE. | | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``demand_rate_livestock`` | Demand for water for livestock (kg s :sup:`-1`) | None | +| | | | +| | .. note:: | | +| | Required if :nml:mem:`JULES_WATER_RESOURCES::l_water_livestock` | | +| | = TRUE. | | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ +| ``demand_rate_transfers`` | Demand for water for transfers (kg s :sup:`-1`) | None | +| | | | +| | .. note:: | | +| | Required if :nml:mem:`JULES_WATER_RESOURCES::l_water_transfers` | | +| | = TRUE. | | ++---------------------------+-------------------------------------------------------------------+---------------------------------------------------+ + diff --git a/doc/source/namelists/red_parms.nml.rst b/doc/source/namelists/red_parms.nml.rst new file mode 100644 index 00000000..b36c27fe --- /dev/null +++ b/doc/source/namelists/red_parms.nml.rst @@ -0,0 +1,120 @@ + + +This file contains a single namelist called :nml:lst:`JULES_RED` that sets parameters relevant to the Robust Ecosystem Demography submodel (RED version 1.0) `_. +Activate RED in the :nml:mem:`JULES_VEGETATION::l_red. + +``JULES_RED`` namelist members +---------------------------------- + +.. nml:namelist:: RED_PARMS + +This namelist is used to read PFT parameters that are only needed by the Robust Ecosystem Demography (RED). Values are not used if RED is not selected. + +.. note:: Where a quantity is said to have units of "/360days", this means that it is an amount per 360 days. + +.. nml:group:: Only used when :nml:mem:`JULES_VEGETATION::l_red = TRUE + +.. nml:member:: alpha_recrt + + :type: real(npft) + :default: None + + The fraction of PFT carbon assimilate devoted to reproduction. + + +.. nml:member:: crwn_area0 + + :type: real(npft) + :default: None + + The lowest PFT crown area, value corresponds to the mass0 class (m\ :sup:`2`). + + +.. nml:member:: dom_order + + :type: integer(npft) + :default: None + + The value that describes the competitive hierarchy of PFTs competition in + JULES-RED, the higher the value the more dominant: 3 (trees), 2 (shrubs), 1 (grass). + + +.. nml:member:: height0 + + :type: real(npft) + :default: None + + The lowest PFT height, value corresponds to the mass0 class (m). + + +.. nml:member:: lai_bal0 + + :type: real(npft) + :default: None + + The lowest PFT balanced LAI, which corresponds to the mass0 class (m\ :sup:`2`/m\ :sup:`2`). + + +.. nml:member:: mass0 + + :type: real(npft) + :default: None + + The lowest PFT mass class (kg C). + + +.. nml:member:: massi + + :type: real(npft) + :default: None + + The highest PFT mass class (kg C). + + +.. nml:member:: mclass + + :type: integer(npft) + :default: None + + Number of mass classes for each PFT. + + +.. nml:member:: mort_base + + :type: real(npft) + :default: None + + The baseline PFT mortality rate (/360 days). + + +.. nml:member:: phi_a + + :type: real(npft) + :default: 0.50 + + The allometric/power scaling of PFT mass to PFT crown area (West, G. B., et al 2009 `_). + + +.. nml:member:: phi_g + + :type: real(npft) + :default: 0.75 + + The allometric/power scaling of PFT mass to PFT mass growth rate (West, G. B., et al., 1997 `_). + + +.. nml:member:: phi_h + + :type: real(npft) + :default: 0.25 + + The allometric/power scaling of PFT mass to PFT height (Niklas, K. J., et al., 2001 `_). + + +.. nml:member:: phi_l + + :type: real(npft) + :default: 0.25 + + The allometric/power scaling of PFT mass to PFT leaf area index. + diff --git a/doc/source/namelists/science_fixes.nml.rst b/doc/source/namelists/science_fixes.nml.rst new file mode 100644 index 00000000..1b903ef5 --- /dev/null +++ b/doc/source/namelists/science_fixes.nml.rst @@ -0,0 +1,196 @@ +``science_fixes.nml`` +===================== + + +This file contains one namelist called :nml:lst:`JULES_TEMP_FIXES`. + +This namelist sets 'short-term' temporary logicals used to protect science bug +fixes that lead to alterations in science results. It is expected that these +logicals will be short lived as the preference should be for all configurations +to use the corrected code. However, to maintain short term reproducibility of +results across JULES versions the fixes are protected by logicals until the +fixes become the default in all model configurations at which point the logical +is retired. See module for when the switch is due for review. + +``JULES_TEMP_FIXES`` namelist members +------------------------------------- + +.. nml:namelist:: JULES_TEMP_FIXES + +.. nml:member:: ctile_orog_fix + + :type: integer + :permitted: 0-2 + :default: 2 + + If nonzero, corrects the surface exchange calculations in coastally + tiled grid-boxes, assuming that the lowest level is physically + terrain following and adjusting the temperature of the land/sea + portions in accordance with their relative offset from the grid-box + mean height using a dry/moist lapse rate where appropriate. Option 2 + will only adjust values over the sea. + +.. nml:member:: l_accurate_rho + + :type: logical + :default: F + + This switch improves the calculation of surface air density in the + surface turbulent fluxes. It includes appropriate use of dry air density + when the atmospheric water vapour is expressed as a mixing ratio + (l_mr_physics = .TRUE.), otherwise use the wet air density when + it is expressed as a specific humidity. + + +.. nml:member:: l_dtcanfix + + :type: logical + :default: F + + This switch corrects a bug in the evolution of the skin temperature in + the implicit solver, + whereby the change in the skin temperature is + artificially constrained. This generally has a small effect, + but can + cause unphysical results if a canopy with a large heat capacity is + coupled to an underlying substrate with a small heat capacity. + +.. nml:member:: l_fix_alb_ice_thick + + :type: logical + :default: F + + When zero-layer sea ice is used the thermodynamics is calculated in the + UM through an effective thickness calculated from snow and ice thicknesses + and associated thermal conductivities. With multi-layer sea ice the + thermodynamics is calculated in the sea ice component of the model, and + the effective thickness is no longer required. However, it was still + being used erroneously. This fix removes the effective thickness + adjustment when multi-layer sea ice is used. + +.. nml:member:: l_fix_albsnow_ts + + :type: logical + :default: F + + The original version of the two-stream scheme to calculate the albedo + of snow in JULES contains a bug in the calculation of the reflection + coefficient that renders very thin layers of snow too reflective. + This logical applies the appropriate correction when it is enabled. + +.. nml:member:: l_fix_lake_ice_temperatures + + :type: logical + :default: F + + If true, allows sea ice temperatures in lakes to evolve over time + for coupled models when the lake is defined as a sea point but is + not coupled to an ocean model. + +.. nml:member:: l_fix_moruses_roof_rad_coupling + + :type: logical + :default: F + + If true, this switch corrects a bug in the surface energy balance + when the MORUSES radiative roof coupling is used + (see :nml:mem:`JULES_URBAN::l_moruses_storage`). + If false, the thermal conductivity of the soil (hcons) is erroneously + 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 + :default: F + + When set to false, the chlorophyll content used to determine the optical + properties of water, for the ocean surface albedo, are specified in gm-3 + when the parameterisation they use is defined in mg m-3. + It is a short term logical until the code becomes the new default. + +.. nml:member:: l_fix_snow_frac + + :type: logical + :default: F + + When set to false, there is the potential to have small snow mass, but a + zero snow fraction due to machine precision in the calculations. This + prevents sublimation or snow melt from removing the remaining snow mass, + hence small values can persist. + In addition to this there is a conceptual bug in the calculation of + the fraction of potential evaporation because it does not add in canopy + evaporation when the snow fraction is less than one. + When set to true these issues are corrected and in addition the radiation + calculations for snow fraction are also made consistent. + +.. nml:member:: l_fix_ustar_dust + + :type: logical + :default: F + + If true, corrects how ustar is calculated in the exchange + coefficient for dust deposition + +.. nml:member:: l_fix_wind_snow + + :type: logical + :default: F + + If true, ensures that wind speed is calculated for use in snow unloading. + If false, the wind speed for unloading will be zero on timesteps when + 10m wind diagnostics are not calculated. This will tend to leave more + snow on the vegetation. + It is a short term logical until the code becomes the new default. + +.. nml:group:: For UM-coupled JULES applications, the following switches are set during the run to be equivalent to the corresponding switches in the UKCA (which are set in the UM run_ukca namelist). + + .. nml:member:: l_fix_drydep_so2_water + + :type: logical + :default: FALSE + + Switch in UKCA to correct the surface resistance of SO2 to water when calculating + the dry deposition of SO2. If true, a surface resistance value of 10 s m-1 + is used. If false, an incorrect surface resistance value of 148.9 s m-1 is used. + Note: this is being maintained as it was used in UKESM1.0. + + .. nml:member:: l_fix_improve_drydep + + :type: logical + :default: FALSE + + Switch in UKCA to make the surface resistance terms for the 9-tile configuration + consistent with those of the 13, 17 and 27 tile configurations. If true, use + surface resistance terms for the 9-tile configuration that are consistent + with those for the other allowed surface tile configurations. If false, use + the original surface resistance terms for the 9-tile configuration. + + The switch also adjusts the surface resistance terms and hence dry deposition velocities + for the following chemical species: HCl, HOCl, HBr, HOBr, H2SO4, MeOH and Sec_Org. + + .. nml:member:: l_fix_ukca_h2dd_x + + :type: logical + :default: FALSE + + Switch in UKCA to correct a bug in the elements of h2dd_c and h2dd_m used for the calculation of + the H2 dry deposition to shrub and bare soil. If true, use the corrected elements of + h2dd_c and h2dd_m. If false, use the original elements of h2dd_c and h2dd_m. + diff --git a/doc/source/namelists/timesteps.nml.rst b/doc/source/namelists/timesteps.nml.rst new file mode 100644 index 00000000..7670a448 --- /dev/null +++ b/doc/source/namelists/timesteps.nml.rst @@ -0,0 +1,348 @@ +``timesteps.nml`` +================= + + +This file sets the start and end time of the run. It can also be used to specify an optional spin-up procedure. It contains two namelists called :nml:lst:`JULES_TIME` and :nml:lst:`JULES_SPINUP`. + +.. warning:: + It is recommended that all times use not local time, but Coordinated Universal Time (UTC; known in some countries as Greenwich Mean Time GMT). The correct specification of the time is essential if the options causing the surface albedo to depend on the solar zenith angle are set. If the data are provided in local solar time, :nml:mem:`JULES_TIME::l_local_solar_time` should be set to TRUE to assume local solar time throughout the model. + + +``JULES_TIME`` namelist members +------------------------------- + +.. nml:namelist:: JULES_TIME + +.. nml:member:: l_360 + + :type: logical + :default: F + + Switch indicating use of 360 day years. + + TRUE + Each year consists of 360 days. This is sometimes used for idealised experiments. + + FALSE + Each year consists of 365 or 366 days. + + +.. nml:member:: l_leap + + :type: logical + :default: T + + Switch indicating whether the calendar has leap years. This flag is not used if l_360=T. + + TRUE + Leap years are modelled i.e. each year consists of 365 or 366 days. + + FALSE + Each year consists of 365 days. + + +.. nml:member:: l_local_solar_time + + :type: logical + :default: F + + Switch indicating whether the time-stamping of the driving data and throughout the run is to be interpreted as local solar time, not UTC. + + TRUE + The driving data and all times within the model are interpreted as being in local solar time, irrespective of any data attributes. + + FALSE + The time convention applying within the model and the driving data is assumed to be UTC. + + +.. nml:member:: timestep_len + + :type: integer + :permitted: >= 1 + :default: None + + Model timestep length in seconds (n.b. 'special periods' -1 (monthly) and -2 (annual) may not be used). + + Typically, 30 or 60 minutes is chosen, depending on the driving data available. + + .. warning:: + If the timestep is too long, the model becomes numerically unstable. + + +.. nml:member:: main_run_start +.. nml:member:: main_run_end + + :type: character + :default: None + + The start and end times for the integration. + + Each run of JULES consists of an optional spin-up period and the 'main run' that follows the spin-up. See below for more about the specification of the spin-up. These variables specify the start and end times for the 'main run'. + + The times must be given in the format:: + + "yyyy-mm-dd hh:mm:ss" + + +.. nml:member:: print_step + + :type: integer + :permitted: >= 1 + :default: 1 + + Number of timesteps between printing timestep information to screen, i.e. if :nml:mem:`print_step` = 48, then the timestep start time will only be printed every 48 timesteps. + + + +``JULES_SPINUP`` namelist members +--------------------------------- + +.. nml:namelist:: JULES_SPINUP + + +.. nml:member:: max_spinup_cycles + + :type: integer + :permitted: >= 0 + :default: 0 + + The maximum number of times the spin-up period is to be repeated: + + 0 + No spin-up. + + > 0 + At least 1 and at most :nml:mem:`max_spinup_cycles` repetitions of spin-up are used. + + After each repetition, the model tests whether the selected variables have changed by more than a specified amount over the last repetition (see :nml:mem:`tolerance` below). + + If the change is less than this amount, the model is considered to have spun up and the model moves on to the main run. + + +.. nml:member:: spinup_start +.. nml:member:: spinup_end + + :type: character + :default: None + + Only used if :nml:mem:`max_spinup_cycles` > 0. + + The start and end times for each cycle of spin-up. + + The times must be given in the format:: + + "yyyy-mm-dd hh:mm:ss" + + +.. nml:member:: terminate_on_spinup_fail + + :type: logical + :default: F + + Only used if :nml:mem:`max_spinup_cycles` > 0. + + Switch controlling behaviour if the model does not pass the spin-up test after :nml:mem:`max_spinup_cycles` of spin-up. + + TRUE + End the run if model has not spun up. + + FALSE + Continue the run regardless. + + +.. nml:group:: Variables used to specify spin-up conditions + + .. nml:member:: nvars + + :type: integer + :permitted: >= 0 + :default: 0 + + Only used if :nml:mem:`max_spinup_cycles` > 0. + + The number of variables to use to assess if the model has spun up. + + + .. nml:member:: var + + :type: character(nvars) + :default: None + + Only used if :nml:mem:`nvars` > 0. + + List of variables to be used to determine if the model has spun up. Spin-up can be assessed in terms of soil temperature and soil moisture. + + Possible values are: + + ``c_soil`` + Soil carbon in each layer (summed over all pools) (kg m\ :sup:`-2`). + + ``c_veg`` + Vegetation carbon (summed over all vegetation types) (kg m\ :sup:`-2`). + + ``smcl`` + Moisture content of each soil layer (kg m\ :sup:`-2`). + + ``t_soil`` + Temperature of each soil layer (K). + + + .. nml:member:: use_percent + + :type: logical(nvars) + :default: F + + Only used if :nml:mem:`nvars` > 0. + + Indicates whether the tolerance for each variable is expressed as a percentage. + + TRUE + Tolerance is a percentage. + + FALSE + Tolerance is an absolute value. + + + .. nml:member:: tolerance + + :type: real(nvars) + :default: None + + Only used if :nml:mem:`nvars` > 0. + + Tolerance for spin-up test for each variable. + + For each spin-up variable, this is the maximum allowed change over a spin-up cycle if the variable is to be considered as spun-up. + + + +Note on time conventions +------------------------ + +When specifying start times (e.g. :nml:mem:`JULES_TIME::main_run_start`, :nml:mem:`JULES_SPINUP::spinup_start`), the time is taken to be the *start of the first timestep*. When specifying end times (e.g. :nml:mem:`JULES_TIME::main_run_end`, :nml:mem:`JULES_SPINUP::spinup_end`), the time is taken to be the *end of the last timestep*. Also, the time "00:00:00" always refers to midnight at the *start* of the day concerned. Take the following setup:: + + &JULES_TIME + timestep_len = 3600, + main_run_start = "1997-01-01 00:00:00", + main_run_end = "1998-01-01 00:00:00", + + # ... + / + +With this setup, exactly one whole year of timesteps will be run. The first model timestep begins at 1997-01-01 00:00:00, the second at 1997-01-01 01:00:00 etc. The final model timestep begins at 1997-12-31 23:00:00 and ends at 1998-01-01 00:00:00. Note that even though only 1997 is simulated, JULES may nevertheless need to access data file(s) for subsequent timesteps (January 1998 in this example), depending on the interpolation flag settings in :doc:`/input/temporal-interpolation`. + +For example, if your driving data set extends to the end of 1997 only, then you may need to either stop the simulation 1-2 data timesteps before the end of 1997 (by modifying :nml:mem:`JULES_TIME::main_run_end` and :nml:mem:`JULES_SPINUP::spinup_end`; n.b. if these data timesteps are at the end of the year/month then an annual/monthly average will not be calculated) or generate dummy driving data for the start of 1998 (which must be realistic because they will be used for interpolation during the last few model timesteps). + +The maximum extent of your driving data should be specified by :nml:mem:`JULES_DRIVE::data_start` and :nml:mem:`JULES_DRIVE::data_end`. The periods of the main run (:nml:mem:`JULES_TIME::main_run_start` to :nml:mem:`JULES_TIME::main_run_end`) and spin-up (:nml:mem:`JULES_SPINUP::spinup_start` to :nml:mem:`JULES_SPINUP::spinup_end`) must be contained within :nml:mem:`JULES_DRIVE::data_start` to :nml:mem:`JULES_DRIVE::data_end`. + +Note that all times are recommended to be in Coordinated Universal Time (UTC), not local time (see Warning at top of this page). Note also the limitations on timestep mentioned in :doc:`/input/temporal-interpolation` and on run length mentioned in :doc:`/code/known-limitations`. + + + +Note on solar zenith angle +-------------------------- + +When the characteristics of the surface relevant to solar radiation are represented in a simple manner, the cosine of the solar zenith angle itself is not required and all that is needed is the downward shortwave flux provided by the forcing data. In such cases it is sufficient to set :nml:mem:`JULES_RADIATION::l_cosz` = FALSE, which will set the cosine of the solar zenith angle to a default value of 1.0. + +However, more elaborate treatments of the surface albedo and of solar radiative transfer in plant canopies do depend on the actual value of the cosine of the solar zenith angle, as well as the downward flux, so it is more realistic to set :nml:mem:`JULES_RADIATION::l_cosz` = TRUE, and, indeed, the results obtained with :nml:mem:`JULES_RADIATION::l_cosz` = FALSE may be significantly in error. To calculate the cosine of the zenith angle, the times of the forcing data must be specified accurately. The consistent use of UTC is strongly recommended. Nevertheless, certain forcing data, widely used within the land-surface community, are specified in local solar time, even though the metadata in the file may refer to UTC. In such cases :nml:mem:`JULES_TIME::l_local_solar_time` should be set to TRUE when :nml:mem:`JULES_RADIATION::l_cosz` = TRUE. + + +Examples +-------- + +A run without spin-up +~~~~~~~~~~~~~~~~~~~~~ + +:: + + &JULES_TIME + timestep_len = 3600, + main_run_start = "1997-01-01 00:00:00", + main_run_end = "1999-01-01 01:00:00" + / + + &JULES_SPINUP + max_spinup_cycles = 0 + / + +This specifies a run with a timestep length of one hour. The run will begin at midnight on 1st January 1997 and end at 01:00 UTC on 1st January 1999. :nml:mem:`JULES_SPINUP::max_spinup_cycles` = 0 means there is no spin-up. + +A run with spin-up over a period that immediately precedes the main run +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + &JULES_TIME + timestep_len = 3600, + main_run_start = "1997-01-01 00:00:00", + main_run_end = "1999-01-01 01:00:00" + / + + &JULES_SPINUP + max_spinup_cycles = 5, + spinup_start = "1996-01-01 00:00:00", + spinup_end = "1997-01-01 00:00:00" + + # + / + +This specifies a spin-up period from midnight on 1st January 1996 to midnight on 1st January 1997. This spin-up will be repeated up to 5 times, before the main run from midnight on 1st January 1997 until 01:00 UTC on 1st January 1999. + +A run with spin-up over a period that overlaps the main run +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + &JULES_TIME + timestep_len = 3600, + main_run_start = "1997-01-01 00:00:00", + main_run_end = "1999-01-01 01:00:00" + / + + &JULES_SPINUP + max_spinup_cycles = 5, + spinup_start = "1997-01-01 00:00:00", + spinup_end = "1998-01-01 00:00:00" + + # + / + +This specifies a spin-up period from midnight on 1st January 1997 to midnight on 1st January 1998. This spin-up will be repeated up to 5 times, before the main run from midnight on 1st January 1997 until 01:00 UTC on 1st January 1999. + +Example of specifying requirements for spin-up +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + &JULES_SPINUP + # + + terminate_on_spinup_fail = T, + + nvars = 2, + var = "smcl" "t_soil", + use_percent = F T , + tolerance = 1.0 0.1 + / + +With this setup, :nml:mem:`JULES_SPINUP::terminate_on_spinup_fail` = TRUE means that if the spin-up has not 'converged' after :nml:mem:`JULES_SPINUP::max_spinup_cycles` cycles, the run will end. Convergence is measured using the moisture content and temperature of each soil layer. At every point and in every layer, soil moisture must change by less than 1 kg m\ :sup:`-2`, while soil temperature must change by less than 0.1%. + + +Notes on spin-up +---------------- + +Spin-up is assessed using the difference between instantaneous values at the end of consecutive cycles of spin-up. For example, if the spin-up period is from 2005-01-01 00:00:00 to 2006-01-01 00:00:00 then every time the model gets to the end of 2005 the spin-up variables are compared with their value at the end of the previous cycle. The model is considered spun-up when *all* the spin-up variables are spun-up at *all* points. A spin-up variable is considered spun-up if, at each point, the absolute value of the change (percentage change if :nml:mem:`JULES_SPINUP::use_percent` = TRUE) over the spin-up cycle is less than or equal to the given tolerance. + +At present the analysis of whether the model has spun up or not is limited to aspects of the 'physical' state of the system, and does not explicitly consider carbon stores, making it less useful for runs with interactive vegetation (the equilibrium mode of TRIFFID is designed to spin-up TRIFFID) or prognostic soil carbon. + +During the spin-up phase of a run, JULES provides the correct driving data (for example, meteorological data) as the model time 'cycles' round over the spin-up period. Consider the case of a spin-up from 2005-01-01 00:00:00 to 2006-01-01 00:00:00. At or near the end of 31st December 2005 during the spin-up, the driving data will start to adjust to the values for 1st January 2005. The calculated driving data may vary slightly between the start or end of the first cycle and similar times in later cycles, because of the need to match the data at the end of each cycle to that at the start of the next cycle. When the main run begins after a period of spin-up, the driving data is reset to the start of the main run - no effort is made to adjust the data for a smooth transition. Generally this does not cause a problem. + +Depending upon the details of the input data and any temporal interpolation, the driving data may vary rapidly at the end of a cycle of spin-up, causing an extreme response from the model. In most cases the model will adjust, possibly with large heat fluxes over a few hours, but the user should be aware that unusual behaviour near the end/start of a spin-up cycle may be the result of this adjustment. Consider the case of a spin-up from 2005-01-01 00:00:00 to 2006-01-01 00:00:00. At or near the end of 31st December 2005 during the spin-up, the driving data will start to adjust to the values for 1st January 2005, which could be very different from conditions on 31st December 2005. The length of time over which the driving data adjust depends on the frequency of the data, and the choice of temporal interpolation. For example, with 3-hourly data that is interpolated onto a one hour timestep, the adjustment will take place over 3 hours. However, hourly data and an hourly timestep will force an instantaneous adjustment at the start of 1st January 2005. + +Although :nml:mem:`JULES_SPINUP::max_spinup_cycles` specifies the maximum number of spin-up cycles, some of which might not be used if the model is considered to have spun up earlier, it is possible to specify the exact number of cycles that will be performed. This can be done by demanding an impossible level of convergence by setting :nml:mem:`JULES_SPINUP::tolerance` < 0 (remember that :nml:mem:`JULES_SPINUP::tolerance` is compared with the absolute change over a cycle) and setting :nml:mem:`JULES_SPINUP::terminate_on_spinup_fail` = FALSE so that the integration continues when spin-up is judged to have failed after :nml:mem:`JULES_SPINUP::max_spinup_cycles` cycles. + +Although it is expected that a spin-up phase will be followed by the main run in the same integration, it is possible to do the spin-up and main run in separate integrations. This can be done by demanding an impossible level of convergence by setting :nml:mem:`JULES_SPINUP::tolerance` < 0 and setting :nml:mem:`JULES_SPINUP::terminate_on_spinup_fail` = TRUE so that the integration stops when spin-up is judged to have failed. The final state of the model, after :nml:mem:`JULES_SPINUP::max_spinup_cycles` cycles of spin-up, will be written to the final dump, and a subsequent simulation can be started from this dump. + +A limitation of the current code is that it cannot cope with a spin-up cycle that is short in comparison to the period of any input data. For example, a spin-up cycle of 1 day cannot use 10-day vegetation data. The code will likely run but the evolution of the vegetation data will probably not be what the user intended! However, it is unlikely that a user would want to try such a run. + +Occasionally, the model fails to diagnose a spun up state when in fact the integration has reached a quasi-steady state that is not detected by the procedure of assessing spin-up through comparison of instantaneous values at the end of consecutive cycles of spin-up. An example of this is 'period-2' behaviour, where the model state repeats itself over a period of 2 cycles. Such behaviour should be apparent in the model output during spin-up, and the user can opt to repeat the integration over a given number of spin-up cycles, and not to wait for a spun-up state to be diagnosed. diff --git a/doc/source/namelists/triffid_params.nml.rst b/doc/source/namelists/triffid_params.nml.rst new file mode 100644 index 00000000..59931232 --- /dev/null +++ b/doc/source/namelists/triffid_params.nml.rst @@ -0,0 +1,180 @@ +``triffid_params.nml`` +====================== + + +This file contains a single namelist called :nml:lst:`JULES_TRIFFID` that sets parameters relevant to the TRIFFID submodel. + + +``JULES_TRIFFID`` namelist members +---------------------------------- + +.. nml:namelist:: JULES_TRIFFID + +This namelist is used to read PFT parameters that are only needed by the dynamic vegetation model (TRIFFID). Values are not used if TRIFFID is not selected. + +.. note:: Where a quantity is said to have units of "/360days", this means that it is an amount per 360 days. + +.. note:: If the crop model is on (i.e. :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0), only ``nnpft = npft - ncpft`` values will be used for each variable. + + +.. nml:member:: crop_io + + :type: integer(npft) + :permitted: 0,1,2,3 + :default: None + + Flag indicating whether the PFT is natural, crop, or pasture. Only + crop / pasture PFTs are allowed to grow in the agricultural + area. See :nml:mem:`JULES_VEGETATION::l_trif_crop` for more + details. + + | If :nml:mem:`JULES_VEGETATION::l_trif_crop` is FALSE permitted values of ``crop_io`` are 0 and 1. + + 0. Natural vegetation (not a crop). + 1. A crop. + + | If :nml:mem:`JULES_VEGETATION::l_trif_crop` is TRUE permitted values of ``crop_io`` are 0, 1 and 2. + + 0. Natural vegetation (neither crop nor pasture). + 1. Crop. + 2. Pasture. + + | If :nml:mem:`JULES_VEGETATION::l_trif_biocrop` is TRUE permitted values are 0, 1, 2 and 3. Flag indicating whether the PFT is natural, crop, pasture, or bioenergy. See :nml:mem:`JULES_VEGETATION::l_trif_biocrop` for more details. + + 0. Natural vegetation. + 1. Crop. + 2. Pasture. + 3. Bioenergy crops or trees. + +.. nml:member:: g_area_io + + :type: real(npft) + :default: None + + Disturbance rate (/360days). + + +.. nml:member:: g_grow_io + + :type: real(npft) + :default: None + + Rate of leaf growth (/360days). + + +.. nml:member:: g_root_io + + :type: real(npft) + :default: None + + Turnover rate for root biomass (/360days). + + +.. nml:member:: g_wood_io + + :type: real(npft) + :default: None + + Turnover rate for woody biomass (/360days). + + +.. nml:member:: lai_max_io + + :type: real(npft) + :default: None + + Maximum LAI. + + +.. nml:member:: lai_min_io + + :type: real(npft) + :default: None + + Minimum LAI. + + +.. nml:member:: alloc_fast_io + + :type: real(npft) + :default: None + + Fraction of the carbon flux from vegetation to wood products to add to the rapidly decaying wood products pool (wood_prod_fast). + + +.. nml:member:: alloc_med_io + + :type: real(npft) + :default: None + + Fraction of the carbon flux from vegetation to wood products to add to the wood products pool with a moderate decay rate (wood_prod_med). + + +.. nml:member:: alloc_slow_io + + :type: real(npft) + :default: None + + Fraction of the carbon flux from vegetation to wood products to add to the slowly decaying wood products pool (wood_prod_slow). + +.. nml:member:: retran_l_io + + :type: real(npft) + :default: 0.5 + + Fraction of retranslocated leaf N. + +.. nml:member:: retran_r_io + + :type: real(npft) + :default: 0.2 + + Fraction of retranslocated root N. + +.. nml:member:: ag_expand_io + + :type: integer(npft) + :permitted: 0,1 + :default: 0 + + Only used if :nml:mem:`JULES_VEGETATION::l_ag_expand` = TRUE. + + 0. No automatic expansion of PFT area when the agricultural area increases. + 1. Automatically plant out new crop areas with the selected PFT. + +.. nml:group:: Only used when :nml:mem:`JULES_VEGETATION::l_trif_biocrop` = TRUE + + .. nml:member:: harvest_type_io + + :type: integer(npft) + :permitted: 0,1,2 + :default: 0 + + 0. No harvest (default). + 1. Continuous harvest from litter, as per :nml:mem:`JULES_VEGETATION::l_trif_crop`. + 2. Periodic harvesting. + + .. note:: For "natural" PFTs (:nml:mem:`JULES_TRIFFID::crop_io` = 0), this must be set to 0. For agricultural PFTs, this can be set to 0, 1 or 2. + + .. nml:group:: Only used when :nml:mem:`JULES_TRIFFID::harvest_type_io` = 2 + + A placeholder value must be used for all other PFTs. + + .. nml:member:: harvest_freq_io + + :type: integer(npft) + :permitted: >= 0 + :default: none + + Harvest freqency in years. + + .. nml:member:: harvest_ht_io + + :type: real(npft) + :permitted: > 0 + :default: none + + Height [m] to which the PFT is reduced at each harvest cycle. + + .. note:: :nml:mem:`lai_min_io` must be set such that PFT height at :nml:mem:`lai_min_io` <= :nml:mem:`harvest_ht_io`, otherwise JULES will not start (the required value will be shown in error output). + diff --git a/doc/source/namelists/urban.nml.rst b/doc/source/namelists/urban.nml.rst new file mode 100644 index 00000000..e82f7430 --- /dev/null +++ b/doc/source/namelists/urban.nml.rst @@ -0,0 +1,193 @@ +``urban.nml`` +============= + + +This file contains one namelist called :nml:lst:`JULES_URBAN`. + +This section predominantly sets the options available for the two-tile urban scheme MORUSES. These namelists are only read if :nml:mem:`JULES_SURFACE::l_urban2t`, which requires both the :nml:mem:`JULES_SURFACE_TYPES::urban_canyon` and :nml:mem:`JULES_SURFACE_TYPES::urban_roof` surface types to be used. MORUSES provides parameters for: snow free canyon albedo (:nml:mem:`JULES_URBAN::l_moruses_albedo`), canyon emissivity (:nml:mem:`JULES_URBAN::l_moruses_emissivity`), roughness length for heat (:nml:mem:`JULES_URBAN::l_moruses_rough`), roughness length for momentum (:nml:mem:`JULES_URBAN::l_moruses_macdonald`) and thermal inertia (:nml:mem:`JULES_URBAN::l_moruses_storage`). Ancillary data, predominantly required for MORUSES, is read in via :nml:lst:`URBAN_PROPERTIES`. + +For all other parameters that MORUSES does not provide, and for any MORUSES parametrisations that are turned off, values from :doc:`nveg_params.nml` will be used instead. See the switches below for more information. + + + .. seealso:: + References: + + * Porson, A., et al. (2010), Implementation of a new urban energy budget scheme in the MetUM. Part I: Description and idealized simulations, Quarterly Journal of the Royal Meteorological Society, 136: 1514-1529. doi: 10.1002/qj.668 + * Porson, A., et al. (2010), Implementation of a new urban energy budget scheme into MetUM. Part II: Validation against observations and model Intercomparison, Quarterly Journal of the Royal Meteorological Society, 136: 1530-1542. doi: 10.1002/qj.572 + + +``JULES_URBAN`` namelist members +----------------------------------------- + +.. nml:namelist:: JULES_URBAN + +.. nml:member:: anthrop_heat_scale + + :type: real + :default: 1.0 + + Distribution scaling factor, which allows the anthropogenic heat flux to be spread between the :nml:mem:`JULES_SURFACE_TYPES::urban_canyon` and :nml:mem:`JULES_SURFACE_TYPES::urban_roof` surface tiles such that: + + * ``H_roof = anthrop_heat_scale x H_canyon`` + * ``H_canyon x (W/R) + H_roof x ( 1.0 - W/R ) = anthrop_heat`` + + Has a value between 0.0 and 1.0 where the extremes correspond to: + + * 0.0 = all released within the canyon. + * 1.0 = evenly spread between canyon and roof. + + Only used if :nml:mem:`JULES_SURFACE::l_anthrop_heat_src` = TRUE. + + +.. nml:member:: l_moruses_albedo + + :type: logical + :default: F + + MORUSES switch for effective canyon albedo parameterisation (snow free). + + Shortwave radiative exchange in the form of an effective canyon albedo, including shading and multiple reflections, which depends on building materials, geometry and zenith angle. + + TRUE + Use MORUSES parameterisation. Requires that :nml:mem:`JULES_RADIATION::l_cosz` = TRUE. Also, check whether the data are provided in UTC or local solar time. To assume local solar time set :nml:mem:`JULES_TIME::l_local_solar_time` = TRUE. + + FALSE + The snow free canyon albedo is taken from :nml:mem:`JULES_NVEGPARM::albsnf_nvg_io`. + + In all cases the snow covered albedo is :nml:mem:`JULES_NVEGPARM::albsnc_nvg_io`. MORUSES does not parameterise the roof albedo, so this is also taken from :nml:mem:`JULES_NVEGPARM::albsnf_nvg_io`. + + +.. nml:member:: l_moruses_emissivity + + :type: logical + :default: F + + MORUSES switch for effective canyon emissivity parameterisation. + + Long-wave radiative exchange in the form of an effective canyon emissivity, including multiple reflections, which depends on building materials and geometry. + + TRUE + Use MORUSES parameterisation. + + FALSE + The canyon emissivity is taken from :nml:mem:`JULES_NVEGPARM::emis_nvg_io`. + + In either case, the roof emissivity is taken from :nml:mem:`JULES_NVEGPARM::emis_nvg_io`. + + +.. nml:member:: l_moruses_rough + + :type: logical + :default: F + + MORUSES switch for effective roughness length for heat parameterisation. + + The effective roughness length for heat has a physical basis and is not calculated as a fraction of momentum. It depends on the geometry of the canyon, which affects the recirculation of the jet within the canyon. Flow within the canyon can be broken down into two regions; the recirculation and ventilation regions, where the recirculation region forms in the wake of each building. Three different flow regimes are represented: + + 1. Isolated roughness - Canyon has separate recirculation and ventilation regions + 2. Wake interference - Recirculation region begins to impinge on the downstream building + 3. Skimming flow - Recirculation region fills the entire canyon + + | The effective roughness length for heat is calculated using a resistance network within these regions. + + TRUE + Use MORUSES parameterisation for canyon and roof. + + FALSE + Values for canyon and roof are taken from :nml:mem:`JULES_NVEGPARM::z0_nvg_io` and :nml:mem:`JULES_NVEGPARM::z0hm_nvg_io`. + + +.. nml:member:: l_moruses_storage + + :type: logical + :default: F + + MORUSES switch for thermal inertia and coupling with the underlying soil for canyon and roof. + + MORUSES consists of two surfaces; a canyon (:nml:mem:`JULES_SURFACE_TYPES::urban_canyon`) and a roof (:nml:mem:`JULES_SURFACE_TYPES::urban_roof`). This MORUSES parametrisation calculates the heat capacity of each of these surface types and also modifies how they are coupled with the underlying soil. The heat capacities of the canyon and roof are calculated using the properties of the urban fabric and the geometry of the canyon. The roof has a lower thermal inertia and can respond more rapidly to changes in forcing. The nature of the coupling (radiative, conductive or none) is controlled via :nml:mem:`JULES_NVEGPARM::vf_nvg_io` as descibed below. + + **The canyon**: + Consists of two walls and a road where the road only is coupled to the underlying soil. The walls are uncoupled and have a zero-flux boundary condition. The coupling of the road is therefore parametrised using a canyon scaling factor. The nature of the canyon (or road surface) coupling is specified as follows: + + :nml:mem:`JULES_NVEGPARM::vf_nvg_io` (:nml:mem:`JULES_SURFACE_TYPES::urban_canyon`): + = ===================== + 0 conductively coupled + 1 radiatively coupled + = ===================== + + **The roof**: + As the roof is not in direct contact with the soil, it physically cannot be conductively coupled. It can either be radiatively coupled or uncoupled. To allow for no coupling, MORUSES modifies the code to change the meaning of conductively coupled to **NOT** coupled. The nature of the coupling is therefore specified as follows: + + :nml:mem:`JULES_NVEGPARM::vf_nvg_io` (:nml:mem:`JULES_SURFACE_TYPES::urban_roof`): + = ===================== + 0 **NOT** coupled + 1 radiatively coupled + = ===================== + + TRUE + Use MORUSES parameterisation as described above. + + FALSE + Values for canyon and roof are taken from :nml:mem:`JULES_NVEGPARM::ch_nvg_io` and :nml:mem:`JULES_NVEGPARM::vf_nvg_io` (with no modifications to coupling). + + +.. nml:member:: l_moruses_storage_thin + + :type: logical + :default: F + + MORUSES switch to use a thin roof to simulate the effects of insulation. + + Only used if :nml:mem:`l_moruses_storage` = TRUE. + + TRUE + Use thin, insulated roof. + + FALSE + Use damping depth diffusivity of roofing materials. + + +.. nml:member:: l_moruses_macdonald + + :type: logical + :default: F + + MORUSES switch for using MacDonald et al. (1998) to calculate effective roughness length of urban areas and displacement height from urban geometry. + + TRUE + Use MacDonald et al. (1998) formulations. + + FALSE + Appropriate data needs to be supplied instead. + + .. note:: If :nml:mem:`l_urban_empirical` = TRUE then :nml:mem:`l_moruses_macdonald` should also be TRUE, to keep the roughness length and displacement height consistent with the morphology. + + .. seealso:: + References: + + * Macdonald RW, Griffiths RF, Hall D. 1998. An improved method for the estimation of surface roughness of obstacle arrays. Atmos. Env. 32: 1857-1864 + + +.. nml:member:: l_urban_empirical + + :type: logical + :default: F + + Switch to use empirical relationships for urban geometry, based on total urban fraction. Dimensions calculated are W/R, H/W and H. + + If no MORUSES parametrisations are used, i.e. the basic URBAN-2T, then only W/R is required. + + If the roof fraction is not supplied i.e. canyon fraction = total urban fraction, then W/R will be used to calculate the canyon and roof fractions. W/R is also used to distribute anthropogenic heat between the roof and the canyon if :nml:mem:`JULES_SURFACE::l_anthrop_heat_src` = TRUE. + + TRUE + Use empirical relationships for urban geometry. + + FALSE + Appropriate data needs to be supplied instead. + + .. warning:: These are only valid for high resolutions (~1 km). + + .. seealso:: + References: + + * Bohnenstengel SI, Evans S, Clark P, Belcher SE (2010). Simulations of the London urban heat island, Quarterly Journal of the Royal Meteorological Society (submitted) diff --git a/doc/source/output-variables.rst b/doc/source/output-variables.rst new file mode 100644 index 00000000..65d0ef2b --- /dev/null +++ b/doc/source/output-variables.rst @@ -0,0 +1,1456 @@ +.. _output_variables_section: + +JULES Output variables +====================== + + +Variables that are available for output from JULES are listed in this section, separated according to the broad area of science. If a variable cannot be found, users should also check in related sections. + +.. note:: + Most variables are output on the full model grid (even for variables defined on land points only). + + Most river variables are output on the river routing model grid, which is a 1D grid defined on the valid river routing points only. These are indicated by names ending in ``_rp`` and have a single spatial dimension of size ``np_rivers``. A regridded version of some river variables can also be output on the full model grid." + + Any points on the grid for which a variable is not defined with be filled with a missing data value. + + Any variables also available on soil tiles are indicated next to their non-soil-tiled analogues, e.g. ``var[_soilt]``, in which case they have an additional dimension of size ``nsoilt``. + + All variables include a land point dimension, unless specified otherwise. + + The sizes of dimensions are indicated in the tables below using links to other sections of this documentation, wherever possible. Other sizes are discussed in the table below. + +.. tabularcolumns:: |p{2.5cm}|p{12.0cm}| + ++-----------------+--------------------------------------------------------------------------------------------------------+ +| Name | Description | ++=================+========================================================================================================+ +| ``ch4layer`` | Number of soil methane layers. | +| | | +| | Equals :nml:mem:`JULES_SOIL::sm_levels` if :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_ch4_tlayered` = TRUE, | +| | otherwise = 1. | ++-----------------+--------------------------------------------------------------------------------------------------------+ +| ``cslayer`` | Number of layers for soil carbon and nitrogen. | +| | | +| | With the single-pool soil model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 1), | +| | ``cslayer`` = 1. | +| | | +| | With 4-pool model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2), | +| | if :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = TRUE ``cslayer`` = :nml:mem:`JULES_SOIL::sm_levels`, | +| | otherwise ``cslayer`` = 1. | +| | | +| | With the ECOSSE model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 3), | +| | ``cslayer`` = :nml:mem:`JULES_SOIL_ECOSSE::dim_cslayer`. | ++-----------------+--------------------------------------------------------------------------------------------------------+ +| ``cspool`` | Number of soil carbon pools. | +| | | +| | =1 with the single-pool soil model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 1). | +| | | +| | =4 with the 4-pool or ECOSSE models (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3). | ++-----------------+--------------------------------------------------------------------------------------------------------+ +| ``land+sea`` | Variable is available on all points (land and sea). | ++-----------------+--------------------------------------------------------------------------------------------------------+ +| ``ncpft`` | Number of crop plant functional types - see :nml:mem:`JULES_SURFACE_TYPES::ncpft`. | ++-----------------+--------------------------------------------------------------------------------------------------------+ +| ``npft`` | Number of plant functional types - see :nml:mem:`JULES_SURFACE_TYPES::npft`. | ++-----------------+--------------------------------------------------------------------------------------------------------+ +| ``ns_deep`` | The number of levels in the thermal-only bedrock - see :nml:mem:`JULES_SOIL::ns_deep`. | ++-----------------+--------------------------------------------------------------------------------------------------------+ +| ``nsmax`` | Maximum-allowed number of snow layers - see :nml:mem:`JULES_SNOW::nsmax`. | ++-----------------+--------------------------------------------------------------------------------------------------------+ +| ``nsoilt`` | Number of soil tiles. | +| | ``nsurft`` if :nml:mem:`JULES_SOIL::l_tile_soil` = TRUE, otherwise 1. | ++-----------------+--------------------------------------------------------------------------------------------------------+ +| ``nsurft`` | Number of surface tiles. | +| | 1 if :nml:mem:`JULES_SURFACE::l_aggregate` = TRUE, otherwise ``ntype``. | ++-----------------+--------------------------------------------------------------------------------------------------------+ +| ``ntype`` | Number of surface types, | +| | = :nml:mem:`JULES_SURFACE_TYPES::npft` + :nml:mem:`JULES_SURFACE_TYPES::nnvg` | ++-----------------+--------------------------------------------------------------------------------------------------------+ +| ``sm_levels`` | Number of soil layers (for soil moisture) - see :nml:mem:`JULES_SOIL::sm_levels`. | ++-----------------+--------------------------------------------------------------------------------------------------------+ + + + +Meteorology +------------------------------------------------------------------- + +Unlesss stated otherwise these variables have values at both land and sea points. + +.. tabularcolumns:: |p{2.5cm}|p{10.8cm}|p{2.2cm}| + ++---------------------+----------------------------------------------------------------------+-------------+ +| Name | Description | Dimensions | ++=====================+======================================================================+=============+ +| ``precip`` | Gridbox precipitation rate (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``rainfall`` | Gridbox rainfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``snowfall`` | Gridbox snowfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``con_rain`` | Gridbox convective rainfall (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``con_snow`` | Gridbox convective snowfall (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``ls_rain`` | Gridbox large-scale rainfall (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``ls_snow`` | Gridbox large-scale snowfall (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``pstar`` | Gridbox surface pressure (Pa). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``q1p5m_gb`` | Gridbox specific humidity at 1.5m height (kg kg\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``qw1`` | Gridbox specific humidity (total water content) (kg kg\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``q1p5m`` | Tile specific humidity at 1.5m over land tiles (kg kg\ :sup:`-1`). | land,nsurft | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``lw_down`` | Gridbox surface downward LW radiation (W m\ :sup:`-2`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``sw_down`` | Gridbox surface downward SW radiation (W m\ :sup:`-2`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``t1p5m_gb`` | Gridbox temperature at 1.5m height (K). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``t1p5m`` | Tile temperature at 1.5m over land tiles (K). | land,nsurft | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``tl1`` | Gridbox ice/liquid water temperature (K). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``u1`` | Gridbox westerly wind component (m s\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``u10m`` | Gridbox westerly wind component at 10 m height (m s\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``v1`` | Gridbox southerly wind component (m s\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``v10m`` | Gridbox southerly wind component at 10m height (m s\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ +| ``wind`` | Gridbox wind speed (m s\ :sup:`-1`). | | ++---------------------+----------------------------------------------------------------------+-------------+ + + + +Radiation +------------------------------------------------------------------- + +.. tabularcolumns:: |p{3.0cm}|p{10.3cm}|p{2.2cm}| + ++---------------------+-------------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++=====================+=========================================================================+============+ +| Albedos and emissivities | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``albedo_land`` | Gridbox albedo (as used to calculate net shortwave radiation) (-). | | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``alb_tile_1`` | Tile land albedo, waveband 1 (direct beam visible). | nsurft | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``alb_tile_2`` | Tile land albedo, waveband 2 (diffuse visible). | nsurft | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``alb_tile_3`` | Tile land albedo, waveband 3 (direct beam NIR). | nsurft | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``alb_tile_4`` | Tile land albedo, waveband 4 (diffuse NIR). | nsurft | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``land_albedo_1`` | Gridbox band 1 albedo (direct beam visible). | land+sea | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``land_albedo_2`` | Gridbox band 2 albedo (diffuse visible). | land+sea | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``land_albedo_3`` | Gridbox band 3 albedo (direct beam NIR). | land+sea | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``land_albedo_4`` | Gridbox band 4 albedo (diffuse NIR). | land+sea | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``emis_gb`` | Gridbox emissivity. | | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``emis`` | Tile emissivity. | nsurft | ++---------------------+-------------------------------------------------------------------------+------------+ +| Radiation fluxes | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``apar`` | PFT absorbed photosynthetically active radiation (W m\ :sup:`-2`). | npft | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``apar_gb`` | Gridbox absorbed photosynthetically active radiation (W m\ :sup:`-2`). | | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``lw_down_surft`` | Tile downwelling longwave radiation (W m\ :sup:`-2`). | nsurft | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``lw_up_surft`` | Tile upwelling longwave radiation (W m\ :sup:`-2`). | nsurft | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``lw_net`` | Gridbox surface net LW radiation (W m\ :sup:`-2`). | | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``lw_up`` | Gridbox surface upward LW radiation (W m\ :sup:`-2`). | | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``rad_net`` | Surface net radiation (W m\ :sup:`-2`). | | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``rad_net_tile`` | Tile surface net radiation (W m\ :sup:`-2`). | nsurft | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``sw_net`` | Gribox net shortwave radiation at the surface (W m\ :sup:`-2`). | | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``sw_net_surft`` | Tile net shortwave radiation (W m\ :sup:`-2`). | nsurft | ++---------------------+-------------------------------------------------------------------------+------------+ +| Other radiation variables | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``cosz`` | Cosine of the zenith angle (-). | land+sea | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``diff_frac`` | Gridbox fraction of radiation that is diffuse (-). | land+sea | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``fapar`` | PFT fraction of absorbed photosynthetically active radiation (-). | npft | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``NDVI_land`` | Gridbox NDVI (using sum of direct and diffuse for (NIR-VIS)/(NIR+VIS)). | | ++---------------------+-------------------------------------------------------------------------+------------+ +| ``trad`` | Gridbox effective radiative temperature (K). | | ++---------------------+-------------------------------------------------------------------------+------------+ + + + +Energy and momentum fluxes, and surface temperatures +------------------------------------------------------------------- + +.. tabularcolumns:: |p{3.5cm}|p{9.8cm}|p{2.2cm}| + ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++=========================+=====================================================================================+============+ +| ``ftl`` | Tile surface sensible heat flux for land tiles (W m\ :sup:`-2`). | nsurft | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``ftl_gb`` | Gridbox surface sensible heat flux (W m\ :sup:`-2`). | land+sea | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``le`` | Tile surface latent heat flux for land tiles (W m\ :sup:`-2`). | nsurft | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``latent_heat`` | Gridbox surface latent heat flux (W m\ :sup:`-2`). | land+sea | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``surf_ht_flux`` | Downward heat flux for each tile (W m\ :sup:`-2`). | nsurft | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``surf_ht_store`` | C*(dT/dt) for each tile (W m\ :sup:`-2`). | nsurft | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``surf_ht_flux_gb`` | Gridbox net downward heat flux at surface over land and sea-ice fraction of gridbox | land+sea | +| | (W m\ :sup:`-2`). | | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``anthrop_heat`` | Anthropogenic heat flux for each tile (W m\ :sup:`-2`). | nsurft | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``hf_snow_melt`` | Gridbox snowmelt heat flux (W m\ :sup:`-2`). | | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``snomlt_surf_htf`` | Gridbox heat flux used for surface melting of snow (W m\ :sup:`-2`). | land+sea | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``snomlt_sub_htf`` | Gridbox sub-canopy snowmelt heat flux (W m\ :sup:`-2`). | | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``tstar_gb`` | Gridbox surface temperature (K). | land+sea | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``tstar`` | Tile surface temperature (K). | nsurft | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``tsurf_elev_surft`` | Tile temperature of elevated subsurface tiles (K). | nsurft | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``tau`` | Tile surface wind stress for land tiles (N m\ :sup:`-2`). | nsurft | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``taux1`` | Gridbox westerly component of surface wind stress (N m\ :sup:`-2`). | land+sea | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``tauy1`` | Gridbox southerly component of surface wind stress (N m\ :sup:`-2`). | land+sea | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``tauy_gb`` | Gridbox scalar magnitude of surface wind stress (N m\ :sup:`-2`). | land+sea | ++-------------------------+-------------------------------------------------------------------------------------+------------+ +| ``z0`` | Tile surface roughness (m). | nsurft | ++-------------------------+-------------------------------------------------------------------------------------+------------+ + + + +Soil moisture and temperature, and soil characteristics +------------------------------------------------------------------- + +.. tabularcolumns:: |p{4.0cm}|p{9.3cm}|p{2.2cm}| + ++-------------------------+-------------------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++=========================+===============================================================================+============+ +| Soil moisture | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``smcl[_soilt]`` | Moisture content of each soil layer (kg m\ :sup:`-2`). | sm_levels | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``soil_wet`` | Total moisture content of each soil layer, as fraction of saturation (-). | sm_levels | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``sthu[_soilt]`` | Unfrozen moisture content of each soil layer as a fraction of saturation (-). | sm_levels | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``sthu_irr[_soilt]`` | Unfrozen moisture content of each soil layer as a fraction of saturation in | sm_levels | +| | irrigated fraction (-) (only available if l_irrig_dmd = T). | | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``sthf[_soilt]`` | Frozen moisture content of each soil layer as a fraction of saturation (-). | sm_levels | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``smc_tot`` | Gridbox total soil moisture in column (kg m\ :sup:`-2`). | | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``swet_liq_tot`` | Gridbox unfrozen soil moisture as fraction of saturation (-). | | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``swet_tot`` | Gridbox soil moisture as fraction of saturation (-). | | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``sthzw[_soilt]`` | Soil wetness in the deep LSH/TOPMODEL layer (-). | | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``zw[_soilt]`` | Gridbox mean depth to water table (m). | | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| Soil temperature | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``t_soil[_soilt]`` | Sub-surface temperature of each layer (K). | sm_levels | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``tsoil_deep`` | Temperature of each bedrock layer (K). | ns_deep | +| | Only available when :nml:mem:`JULES_SOIL::l_bedrock` = TRUE. | | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``depth_frozen`` | Gridbox depth of frozen ground at surface defined from soil temperature (m). | | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``depth_frozen_sthf`` | Gridbox depth of frozen ground at surface defined from soil moisture (m). | | +| | Recommended over ``depth_frozen`` except where the soil is very dry. | | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``depth_unfrozen`` | Gridbox depth of unfrozen ground at surface defined from soil temperature (m).| | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``depth_unfrozen_sthf`` | Gridbox depth of unfrozen ground at surface defined from soil moisture (m). | | +| | Recommended over ``depth_unfrozen`` except where the soil is very dry. | | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| Soil characteristics | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``b[_soilt]`` | Brooks-Corey exponent for each soil layer (-). | sm_levels | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``hcap[_soilt]`` | Dry soil heat capacity (J K\ :sup:`-1` m\ :sup:`-3`) for each soil layer. | sm_levels | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``hcon[_soilt]`` | Dry soil thermal conductivity (W m\ :sup:`-1` K\ :sup:`-1`) for each soil | sm_levels | +| | layer. | | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``satcon[_soilt]`` | Saturated hydraulic conductivity (kg m\ :sup:`-2` s\ :sup:`-1`) for each soil | sm_levels | +| | layer. | | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``sathh[_soilt]`` | Saturated soil water pressure (m) for each soil layer. | sm_levels | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``sm_crit[_soilt]`` | Volumetric moisture content at critical point for each soil layer (-), | sm_levels | +| | as given in :nml:lst:`JULES_SOIL_PROPS`. | | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``sm_sat[_soilt]`` | Volumetric moisture content at saturation for each soil layer (-). | sm_levels | ++-------------------------+-------------------------------------------------------------------------------+------------+ +| ``sm_wilt[_soilt]`` | Volumetric moisture content at wilting point for each soil layer (-), | sm_levels | +| | as given in :nml:lst:`JULES_SOIL_PROPS`. | | ++-------------------------+-------------------------------------------------------------------------------+------------+ + + + +Hydrology +------------------------------------------------------------------- + +.. tabularcolumns:: |p{4.6cm}|p{8.7cm}|p{2.2cm}| + ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++===============================+===============================================================================================+============+ +| Canopy hydrology | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``canopy_gb`` | Gridbox canopy water content (kg m\ :sup:`-2`). | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``canopy`` | Tile surface/canopy water for snow-free land tiles (kg m\ :sup:`-2`). | nsurft | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``catch`` | Tile surface/canopy water capacity of snow-free land tiles (kg m\ :sup:`-2`). | nsurft | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``tfall`` | Gridbox throughfall (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| Evaporation and sublimation | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``fqw`` | Tile surface moisture flux for land tiles (kg m\ :sup:`-2` s\ :sup:`-1`). | nsurft | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``fqw_gb`` | Gridbox moisture flux from surface (kg m\ :sup:`-2` s\ :sup:`-1`). | land+sea | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``ecan`` | Tile evaporation from canopy/surface store for snow-free | | +| | land tiles (kg m\ :sup:`-2` s\ :sup:`-1`). | nsurft | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``ecan_gb`` | Gridbox mean evaporation from canopy/surface store (kg m\ :sup:`-2` s\ :sup:`-1`). | land+sea | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``ei`` | Tile sublimation from lying snow for land tiles (kg m\ :sup:`-2` s\ :sup:`-1`). | nsurft | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``ei_gb`` | Gridbox sublimation from lying snow or sea-ice (kg m\ :sup:`-2` s\ :sup:`-1`). | land+sea | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``elake`` | Gridbox mean evaporation from lakes (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``esoil`` | Tile surface evapotranspiration from soil moisture store for | nsurft | +| | snow-free land tile (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``esoil_gb`` | Gridbox surface evapotranspiration from soil moisture store (kg m\ :sup:`-2` s\ :sup:`-1`). | land+sea | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``et_stom`` | Tile transpiration (kg m\ :sup:`-2` s\ :sup:`-1`). | nsurft | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``et_stom_gb`` | Gridbox transpiration (kg m\ :sup:`-2` s\ :sup:`-1`). | land+sea | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``fao_et0`` | FAO Penman-Monteith evapotranspiration for reference crop (kg m\ :sup:`-2` s\ :sup:`-1`) | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``gc`` | Tile surface conductance to evaporation for land tiles (m s\ :sup:`-1`). | nsurft | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``gs`` | Gridbox surface conductance to evaporation (m s\ :sup:`-1`). | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``ext[_soilt]`` | Extraction of water from each soil layer (kg m\ :sup:`-2` s\ :sup:`-1`). | sm_levels | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``fsmc_gb`` | Gridbox soil moisture availability factor (beta) (-). | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``fsmc`` | PFT soil moisture availability factor (-). | npft | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``smc_avail_top`` | Gridbox available moisture in surface layer of depth given by :nml:mem:`JULES_SOIL::zsmc` | | +| | (kg m\ :sup:`-2`). Calculated using ``sm_wilt`` from :nml:lst:`JULES_SOIL_PROPS`. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``smc_avail_tot`` | Gridbox available moisture in soil column (kg m\ :sup:`-2`). | | +| | Calculated using ``sm_wilt`` from :nml:lst:`JULES_SOIL_PROPS`. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| Runoff | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``runoff`` | Gridbox runoff rate (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``sub_surf_roff`` | Gridbox sub-surface runoff (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``surf_roff`` | Gridbox surface runoff (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``sat_excess_roff[_soilt]`` | Gridbox saturation excess runoff rate (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``drain[_soilt]`` | Gridbox drainage at bottom of soil column (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``qbase[_soilt]`` | Gridbox baseflow (lateral subsurface runoff) (kg m\ :sup:`-2` s\ :sup:`-1`), i.e. the sum of | | +| | surface and subsurface lateral flows from all soil layers (inc. deep LSH/TOPMODEL layer). | | +| | Only available if :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``qbase_zw[_soilt]`` | Gridbox baseflow (lateral subsurface runoff) from deep LSH/TOPMODEL layer | | +| | (kg m\ :sup:`-2` s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| Other hydrological variables | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``fsat[_soilt]`` | Gridbox surface saturated fraction (-). The fraction of grid cell where the water table is | | +| | above the land surface. Only available if :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``fwetl[_soilt]`` | Gridbox wetland fraction at end of model timestep (-). The fraction of grid cell where the | | +| | water table is above the land surface, but water is not flowing (stagnant) (fwetl<=fsat). | | +| | Only available if :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ + + + +Rivers +------------------------------------------------------------------- + +.. tabularcolumns:: |p{4.6cm}|p{8.7cm}|p{2.2cm}| + ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++===============================+===============================================================================================+============+ +| Output on the river routing model grid | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``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 rivers_outflow_number (see :ref:`list-of-rivers-params`), 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. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``rrun_surf_rp`` | River routing gridbox surface 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. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``rrun_sub_surf_rp`` | River routing gridbox sub-surface 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. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``rfm_surfstore_rp`` | Surface storage on river points (m\ :sup:`3`). | np_rivers | +| | Only available if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE and | | +| | :nml:mem:`JULES_RIVERS::i_river_vn` = 2. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``rfm_substore_rp`` | Sub-surface storage on river points (m\ :sup:`3`). | np_rivers | +| | Only available if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE and | | +| | :nml:mem:`JULES_RIVERS::i_river_vn` = 2. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``rfm_flowin_rp`` | Surface inflow on river points (m\ :sup:`3` s\ :sup:`-1`). | np_rivers | +| | Only available if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE and | | +| | :nml:mem:`JULES_RIVERS::i_river_vn` = 2. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``rfm_bflowin_rp`` | Sub-surface inflow on river points (m\ :sup:`3` s\ :sup:`-1`). | np_rivers | +| | Only available if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE and | | +| | :nml:mem:`JULES_RIVERS::i_river_vn` = 2. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``rivers_sto_rp`` | River routing gridbox river storage (kg) | np_rivers | +| | Only available if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE and | | +| | :nml:mem:`JULES_RIVERS::i_river_vn` = 3. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``frac_fplain_rp`` | Overbank inundation area as a fraction of river routing gridcell area. | np_rivers | +| | Only available if :nml:mem:`JULES_RIVERS::l_riv_overbank` = TRUE. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| Output regridded to the JULES model grid | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``rflow`` | Gridbox river flow rate (kg m\ :sup:`-2` s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``rrun`` | Gridbox runoff rate received by river routing routine (kg m\ :sup:`-2` s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_RIVERS::l_rivers` = TRUE | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ +| ``frac_fplain_lp`` | Overbank inundation area as a fraction of gridcell area. | | +| | Only available if :nml:mem:`JULES_RIVERS::l_riv_overbank` = TRUE. | | ++-------------------------------+-----------------------------------------------------------------------------------------------+------------+ + + + +Snow +------------------------------------------------------------------- + +.. tabularcolumns:: |p{4.5cm}|p{8.8cm}|p{2.2cm}| + ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| Name | Description | Dimensions | ++==========================+===================================================================================+==============+ +| Snow state | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_mass`` | Tile lying snow (total) (kg m\ :sup:`-2`). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_mass_gb`` | Gridbox snowmass (kg m\ :sup:`-2`). | land+sea | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_depth`` | Tile snow depth (m). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_depth_gb`` | Gridbox depth of snow (m). | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_can`` | Tile snow on canopy (kg m\ :sup:`-2`). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_can_gb`` | Gridbox snow on canopy (kg m\ :sup:`-2`). | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_ground`` | Tile snow on ground (``snow_tile`` or ``snow_grnd`` depending | nsurft | +| | on configuration) (kg m\ :sup:`-2`). | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_grnd_gb`` | Gridbox average snow beneath canopy (snow_grnd) (kg m\ :sup:`-2`). | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_grnd`` | Tile snow on ground below canopy (kg m\ :sup:`-2`). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_grnd_rho`` | Tile bulk density of snow on ground (kg m\ :sup:`-3`). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_frac`` | Gridbox snow-covered fraction of land points (-). | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_ice_tile`` | Tile total frozen mass in snow on ground (kg m\ :sup:`-2`). | nsurft | +| | Only available if :nml:mem:`JULES_SNOW::nsmax` > 0. | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_ice_gb`` | Gridbox frozen water in snowpack (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SNOW::nsmax` > 0. | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_liq_tile`` | Tile total liquid mass in snow on ground (kg m\ :sup:`-2`). | nsurft | +| | Only available if :nml:mem:`JULES_SNOW::nsmax` > 0. | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_liq_gb`` | Gridbox liquid water in snowpack (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SNOW::nsmax` > 0. | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``nsnow`` | Tile number of snow layers (-). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``rgrain`` | Tile snow surface grain size (\ |mu|\ m). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| Snow layer variables | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_ds`` | Depth of each snow layer for each tile (m). | nsurft,nsmax | +| | Only available if :nml:mem:`JULES_SNOW::nsmax` > 0. | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_ice`` | Mass of ice in each snow layer for each tile (kg m\ :sup:`-2`). | nsurft,nsmax | +| | Only available if :nml:mem:`JULES_SNOW::nsmax` > 0. | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_liq`` | Mass of liquid water in each snow layer for each tile (kg m\ :sup:`-2`). | nsurft,nsmax | +| | Only available if :nml:mem:`JULES_SNOW::nsmax` > 0. | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``tsnow`` | Temperature of each snow layer (K). | nsurft,nsmax | +| | Only available if :nml:mem:`JULES_SNOW::nsmax` > 0. | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``rgrainl`` | Grain size in snow layers for each tile (\ |mu|\ m). | nsurft,nsmax | +| | Only available if :nml:mem:`JULES_SNOW::nsmax` > 0. | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| Snow fluxes and rates of change | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_melt`` | Tile snow melt rate (melt_tile) (kg m\ :sup:`-2` s\ :sup:`-1`). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_melt_gb`` | Gridbox rate of snowmelt (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_can_melt`` | Tile melt of snow on canopy (kg m\ :sup:`-2` s\ :sup:`-1`). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snice_freez_surft`` | Tile internal refreezing rate in snowpack (kg m\ :sup:`-2` s\ :sup:`-1`). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snice_m_surft`` | Tile total internal melt rate of snowpack (kg m\ :sup:`-2` s\ :sup:`-1`). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snice_runoff_surft`` | Tile net rate of liquid leaving snowpack on tiles (kg m\ :sup:`-2` s\ :sup:`-1`). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snice_sicerate_surft`` | Tile rate of change of solid mass in snowpack (kg m\ :sup:`-2` s\ :sup:`-1`). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snice_sliqrate_surft`` | Tile rate of change of liquid in snowpack (kg m\ :sup:`-2` s\ :sup:`-1`). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snice_smb_surft`` | Tile rate of change of snowpack mass (kg m\ :sup:`-2` s\ :sup:`-1`). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ +| ``snow_soil_htf`` | Tile downward heat flux after snowpack to subsurface" (W m\ :sup:`-2`). | nsurft | ++--------------------------+-----------------------------------------------------------------------------------+--------------+ + + + +Vegetation carbon and related fluxes +------------------------------------------------------------------- + +.. tabularcolumns:: |p{3.5cm}|p{9.8cm}|p{2.2cm}| + ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++==========================+===================================================================================================+============+ +| ``c_veg`` | PFT total carbon content of the vegetation at end of model timestep (kg C m\ :sup:`-2`). | npft | +| | (including leaf, wood and root carbon, both above and below ground) | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``cv`` | Gridbox mean vegetation carbon at end of model timestep (kg m\ :sup:`-2`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``leafC`` | PFT carbon in leaf biomass (kg m\ :sup:`-2` ). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``rootC`` | PFT carbon in root biomass (kg m\ :sup:`-2` ). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``woodC`` | PFT carbon in woody biomass (kg m\ :sup:`-2` ). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``frac_agr`` | Fractional area of agricultural land in each gridbox. If :nml:mem:`JULES_VEGETATION::l_trif_crop` | | +| | is TRUE, frac_agr is the fractional area of crop land in each gridbox. | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``frac_agr_prev`` | Fractional area of agricultural land at the previous timestep. | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``frac_past`` | Fractional area of pasture land in each gridbox. | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``plantNumDensity`` | Number density of plants ( m\ :sup:`-2` ). | npft,nmasst| ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| Fractional cover, leaf area and turnover, and canopy height | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``frac`` | Fractional cover of each surface type. | ntype | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``lai`` | PFT leaf area index (-). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``lai_gb`` | Gridbox leaf area index (-). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``lai_bal`` | PFT balanced leaf area index in sf_stom (-). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``lai_phen`` | PFT leaf area index after phenology (-). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``canht`` | PFT canopy height (m). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``g_leaf`` | PFT leaf turnover rate ([360days]\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``g_leaf_day`` | PFT mean leaf turnover rate for input to PHENOL ([360days]\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``g_leaf_dr_out`` | PFT mean leaf turnover rate for driving TRIFFID ([360days]\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``g_leaf_phen`` | PFT mean leaf turnover rate over phenology period([360days]\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| GPP, NPP, respiration | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``gpp`` | PFT gross primary productivity of biomass expressed as carbon | npft | +| | (kg C m\ :sup:`-2` s\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``gpp_gb`` | Gridbox gross primary productivity of biomass expressed as carbon | | +| | (kg C m\ :sup:`-2` s\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``npp`` | PFT net primary productivity of biomass expressed as carbon prior to nitrogen limitation | npft | +| | (kg C m\ :sup:`-2` s\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``npp_n_gb`` | Gridbox net primary productivity of biomass expressed as carbon after nitrogen limitation | | +| | (kg C m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``npp_n`` | PFT net primary productivity of biomass expressed as carbon after nitrogen limitation | npft | +| | (kg C m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``npp_dr_out`` | PFT mean NPP of biomass expressed as carbon for driving TRIFFID | npft | +| | (kg C m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``nbp_gb`` | Gridbox mean net biosphere productivity. This is NPP minus the sum of all carbon fluxes out of | | +| | land: soil respiration, exudates, harvest flux, wood product pool decay fluxes, and loss of | | +| | carbon from vegetation and soil due to fire (kg C m\ :sup:`-2` (360days)\ :sup:`-1`) | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``resp_p`` | PFT plant respiration carbon flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``resp_p_gb`` | Gridbox plant respiration carbon flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``resp_w_dr_out`` | PFT mean wood respiration carbon flux for driving TRIFFID | npft | +| | (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``resp_l`` | PFT leaf respiration carbon flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``resp_r`` | PFT root respiration carbon flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``resp_w`` | PFT wood respiration carbon flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| Litter carbon fluxes | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``lit_c`` | PFT carbon litter (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``lit_c_mean`` | Gridbox mean carbon litter (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``lit_c_ag`` | PFT carbon litter from LU/agriculture (kg C m\ :sup:`-2` (360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``lit_c_orig`` | PFT carbon litter including LU (kg C m\ :sup:`-2` (360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``leaf_litC`` | PFT litter carbon due to leaf turnover (kg m\ :sup:`-2` )(360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``root_litC`` | PFT litter carbon due to root turnover (kg m\ :sup:`-2` )(360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``wood_litC`` | PFT litter carbon due to wood turnover (kg m\ :sup:`-2` )(360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``plant_input_c_gb`` | Gridbox input of C to the soil by plant litterfall (kg m\ :sup:`-2` s\ :sup:`-1`). | | +| | Only available with the ECOSSE soil model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 3). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| Other carbon fluxes | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``exudates`` | PFT exudates - excess carbon not assimilable into plant due lack of nitrogen | npft | +| | availability (kg C m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``exudates_gb`` | Gridbox exudates: excess carbon not assimilable into plant due lack of nitrogen | | +| | (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``pc_s`` | PFT net carbon available for spreading in TRIFFID | npft | +| | (kg m\ :sup:`-2` (360 days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| Harvest, wood products and land use | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``root_abandon`` | PFT carbon flux from roots abandoned during landuse change to soil | npft | +| | (kg C m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``root_abandon_gb`` | Carbon from roots abandoned during landuse change to soil kg C m\ :sup:`-2` (360days)\ :sup:`-1`).| | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``harvest`` | Flux of carbon to product pools due to harvest (kg C m\ :sup:`-2` (360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``harvest_gb`` | Gridbox flux of carbon to product pools due to harvest (kg C m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``harvest_biocrop`` | Flux of carbon to product pools due to biocrop harvest (kg C m\ :sup:`-2` (360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``harvest_biocrop_gb`` | Gridbox flux of carbon to product pools due to biocrop harvest (kg C m\ :sup:`-2` | | +| | (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``wood_prod_fast`` | Carbon content of the fast decay-rate wood product pool (kg m\ :sup:`-2`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``wood_prod_med`` | Carbon content of the medium decay-rate wood product pool (kg m\ :sup:`-2`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``wood_prod_slow`` | Carbon content of the slow decay-rate wood product pool (kg m\ :sup:`-2`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``WP_fast_in`` | Carbon flux from vegetation to the fast decay-rate wood product pool | | +| | (kg m\ :sup:`-2` [360days]\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``WP_med_in`` | Carbon flux from vegetation to the medium decay-rate wood product pool | | +| | (kg m\ :sup:`-2` [360days]\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``WP_slow_in`` | Carbon flux from vegetation to the slow decay-rate wood product pool | | +| | (kg m\ :sup:`-2` [360days]\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``WP_fast_out`` | Carbon flux from the fast decay-rate wood product pool to atmosphere | | +| | (kg m\ :sup:`-2` [360days]\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``WP_med_out`` | Carbon flux from the medium decay-rate wood product pool to atmosphere | | +| | (kg m\ :sup:`-2` [360days]\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``WP_slow_out`` | Carbon flux from the slow decay-rate wood product pool to atmosphere | | +| | (kg m\ :sup:`-2` [360days]\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| Carbon conservation | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``cnsrv_carbon_veg2`` | Error in land carbon conservation in veg2 routine (kg m-2) | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``cnsrv_carbon_triffid`` | Error in land carbon conservation in triffid routine (kg m-2) | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``cnsrv_veg_triffid`` | Error in vegetation carbon conservation in triffid routine (kg m-2) | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``cnsrv_soil_triffid`` | Error in soil carbon conservation in triffid routine (kg m-2) | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``cnsrv_prod_triffid`` | Error in wood product carbon conservation in triffid routine (kg m-2) | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| Thermal acclimation of photosynthesis | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``t_home_gb`` | Long-term home temperature for C3 photosynthesis (K). | | +| | Only available if :nml:mem:`JULES_VEGETATION::photo_acclim_model` = 1 or 3. | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``t_growth_gb`` | Short-term growth temperature for C3 photosynthesis (K). | | +| | Only available if :nml:mem:`JULES_VEGETATION::photo_acclim_model` = 2 or 3. | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ + + + +Vegetation nitrogen and related fluxes +------------------------------------------------------------------- + +.. tabularcolumns:: |p{4.5cm}|p{8.8cm}|p{2.2cm}| + ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++==========================+===================================================================================================+============+ +| ``n_veg`` | PFT plant nitrogen content N_LEAF+N_ROOT+N_WOOD from carbon equivalents | npft | +| | (kg m\ :sup:`-2`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_veg_gb`` | Gridbox mean plant nitrogen content: n_leaf+n_root+n_wood from carbon equivalents | | +| | (kg m\ :sup:`-2` ). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_leaf`` | PFT leaf nitrogen scaled by LAI in sf_stom (kg m\ :sup:`-2`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_root`` | PFT root nitrogen scaled by LAI_BAL in sf_stom (kg m\ :sup:`-2`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_stem`` | PFT stem nitrogen scaled by LAI in sf_stom; scaled by LAI_BAL if l_stem_resp_fix=T | npft | +| | (kg m\ :sup:`-2`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| Nitrogen fluxes | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``deposition_n`` | Nitrogen deposition (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_demand`` | PFT total nitrogen demand | npft | +| | (kg m\ :sup:`-2` (360 days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_demand_gb`` | Gridbox mean demand for nitrogen (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_fix`` | PFT fixed nitrogen (kg N m\ :sup:`-2` (360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_fix_gb`` | Gridbox mean nitrogen fixed by plants (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_uptake`` | PFT nitrogen taken up by plants (kg m\ :sup:`-2` (360 days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_uptake_gb`` | Gridbox total nitrogen uptake by plants (kg N m\ :sup:`-2` (360days)\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3. | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_demand_growth`` | PFT nitrogen demand for growth of existing plant biomass | npft | +| | (kg m\ :sup:`-2` (360 days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_uptake_growth`` | PFT nitrogen taken up for growth of existing plant biomass | npft | +| | (kg m\ :sup:`-2` (360 days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_demand_lit`` | PFT nitrogen demand of litter: nitrogen lost in leaf, wood and root biomass | npft | +| | (kg m\ :sup:`-2` (360 days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_demand_spread`` | PFT nitrogen demand for spreading plants across gridbox | npft | +| | (kg m\ :sup:`-2` (360 days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``n_fertiliser`` | Nitrogen addition from fertiliser (kg N m\ :sup:`-2` (360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| Nitrogen fluxes in litter, harvest and land use | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``lit_n_t`` | Gridbox mean total nitrogen litter (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | +| | (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``lit_n`` | PFT nitrogen litter (kg N m\ :sup:`-2` (360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``leaf_litN`` | PFT litter nitrogen due to leaf turnover (kg m\ :sup:`-2` )(360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``lit_n_ag`` | PFT nitrogen loss due to LU/agriculture (kg N m\ :sup:`-2` (360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``litterN`` | PFT local nitrogen litter production (kg N m\ :sup:`-2` (360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``lit_n_orig`` | PFT nitrogen litter including LU (kg N m\ :sup:`-2` (360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``root_litN`` | PFT nitrogen lost as litter due to root turnover (kg m\ :sup:`-2` )(360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``wood_litN`` | PFT litter nitrogen due to wood turnover (kg m\ :sup:`-2` )(360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``plant_input_n_gb`` | Gridbox input of N to the soil by plant litterfall (kg m\ :sup:`-2` s\ :sup:`-1`). | | +| | Only available with the ECOSSE soil model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 3). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``harvest_n`` | flux of nitrogen to atmosphere due to harvest (kg N m\ :sup:`-2` (360days)\ :sup:`-1`). | npft | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``harvest_n_gb`` | Gridbox flux of nitrogen to atmosphere due to harvest (kg N m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``harvest_biocrop_n`` | flux of nitrogen to product pools due to biocrop harvest (kg N m\ :sup:`-2` | npft | +| | (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``harvest_biocrop_n_gb`` | Gridbox flux of nitrogen to product pools due to biocrop harvest (kg N m\ :sup:`-2` | | +| | (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``root_abandon_n`` | PFT nitrogen flux from roots abandoned during landuse change to soil | npft | +| | (kg N m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``root_abandon_n_gb`` | Nitrogen from roots abandoned during landuse change to soil | | +| | kg N m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| Nitrogen conservation | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``cnsrv_nitrogen_triffd``| Error in land nitrogen conservation in triffid routine (kg m-2) | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``cnsrv_vegN_triffid`` | Error in vegetation nitrogen conservation in triffid routine (kg m-2) | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``cnsrv_soilN_triffid`` | Error in soil nitrogen conservation in triffid routine (kg m-2) | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ +| ``cnsrv_n_inorg_triffid``| Error in inorganic nitrogen conservation in triffid routine (kg m-2) | | ++--------------------------+---------------------------------------------------------------------------------------------------+------------+ + + + +Soil carbon and related fluxes +------------------------------------------------------------------- + +.. tabularcolumns:: |p{4.6cm}|p{8.7cm}|p{2.2cm}| + ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| Name | Description | Dimensions | ++=============================+===============================================================================================+================+ +| ``cs[_soilt]`` | Carbon in each soil pool and each soil biogeochemistry layer | cspool,cslayer | +| | (kg m\ :sup:`-2`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``cs_label`` | Labelled carbon in each soil pool and each soil biogeochemistry layer (kg m\ :sup:`-2`). | cspool,cslayer | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_label_frac_cs` = TRUE. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``cs_gb`` | Gridbox total soil carbon (kg m\ :sup:`-2`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``cs_label_gb`` | Gridbox total labelled soil carbon (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_label_frac_cs` = TRUE. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``c_bio_gb`` | Gridbox soil carbon in biomass pool (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``c_dpm_gb`` | Gridbox soil carbon in decomposable plant material pool (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``c_hum_gb`` | Gridbox soil carbon in humus pool (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``c_rpm_gb`` | Gridbox soil carbon in resistant plant material pool (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| Soil carbon fluxes | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``co2_soil_gb`` | Gridbox C in CO\ :sub:`2` flux from soil to atmosphere (kg m\ :sup:`-2` s\ :sup:`-1`). | | +| | Only available with the ECOSSE soil model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` | | +| | = 3). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``resp_s`` | Respiration rate from each soil carbon pool each soil biogeochemistry layer | cspool,cslayer | +| | (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``resp_label_cs`` | Respiration rate from each labelled soil carbon pool each soil biogeochemistry layer | cspool,cslayer | +| | (kg m\ :sup:`-2` s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_label_frac_cs` = TRUE. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``resp_s_gb`` | Gridbox total soil respiration carbon flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``resp_label_cs_gb`` | Gridbox total labelled soil respiration carbon flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_label_frac_cs` = TRUE. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``resp_s_to_atmos_gb`` | Respired carbon from soil carbon emitted to atmosphere (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``resp_s_dr_out`` | Gridbox mean soil respiration carbon flux for driving TRIFFID | | +| | (kg m\ :sup:`-2` (360days)\ :sup:`-1`) | | +| | This is the gross soil respiration; some of this carbon flux is from one soil carbon pool to | | +| | another. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| Other soil carbon variables | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``dpm_ratio`` | Gridbox DPM:RPM ratio of overall litter input (:). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``fsth`` | Soil moisture modifier of soil respiration rate (-). | sm_levels | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``ftemp`` | Temperature modifier of soil respiration rate (-). | sm_levels | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``fprf`` | Modifier of soil respiration rate due to vegetation cover (-). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``soil_CN`` | Soil C:N in each soil pool and each soil biogeochemistry layer | cspool,cslayer | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``soil_cn_gb`` | Gridbox total soil carbon : nitrogen ratio. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| Soil methane variables | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``fch4_wetl`` | Gridbox scaled methane flux from wetland fraction using soil carbon as substrate if | | +| | ch4_substrate=1, NPP as substrate if ch4_substrate=2, or soil respiration as substrate if | | +| | ch4_substrate=3 (10\ :sup:`-9` kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``fch4_wetl_cs[_soilt]`` | Gridbox methane flux from wetland fraction using soil carbon as substrate | | +| | (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``fch4_wetl_npp[_soilt]`` | Gridbox methane flux from wetland fraction using NPP as substrate | | +| | (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``fch4_wetl_resps[_soilt]`` | Gridbox methane flux from wetland fraction using soil respiration as substrate | | +| | (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``substr_ch4`` | Carbon in substrate pool used by methanogens for each soil methane layer | ch4layer | +| | (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_ch4_microbe` = TRUE. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``mic_ch4`` | Carbon in methanogenic biomass for each soil methane layer (kg m\ :sup:`-2`). | ch4layer | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_ch4_microbe` = TRUE. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``mic_act_ch4`` | Activity level of methanogenic biomass for each soil methane layer (-). | ch4layer | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_ch4_microbe` = TRUE. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``acclim_ch4`` | Acclimation factor for methanogenic processes in each soil methane layer (-). | ch4layer | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_ch4_microbe` = TRUE. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ + + + +Soil nitrogen and related fluxes +------------------------------------------------------------------- + +.. tabularcolumns:: |p{4.0cm}|p{9.3cm}|p{2.2cm}| + ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| Name | Description | Dimensions | ++=============================+===============================================================================================+================+ +| ``n_soil_gb`` | Gridbox total soil nitrogen (organic and inorganic) (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``ns`` | Gridbox organic nitrogen in each soil pool and each soil biogeochemistry | cspool,cslayer | +| | layer (kg m\ :sup:`-2`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``ns_gb`` | Gridbox soil organic nitrogen (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_bio_gb`` | Gridbox soil nitrogen in biomass pool (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_dpm_gb`` | Gridbox soil nitrogen in decomposable plant material pool (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_rpm_gb`` | Gridbox soil nitrogen in resistant plant material pool (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_hum_gb`` | Gridbox soil nitrogen in humus pool (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_amm_gb`` | Gridbox soil nitrogen in ammonium pool (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 3. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_nit_gb`` | Gridbox soil ammonium in ammonium pool (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 3. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_inorg_gb`` | Gridbox soil inorganic nitrogen (kg m\ :sup:`-2`). | | +| | Only available if :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2 or 3. | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_inorg_avail_pft`` | PFT inorganic nitrogen pool that is available for plant uptake | npft | +| | for each soil biogeochemistry layer (kg m\ :sup:`-2`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| Soil nitrogen fluxes | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``immob_n`` | Soil nitrogen immobilisation in each soil pool | cspool,cslayer | +| | and each soil biogeochemistry layer (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``immob_n_gb`` | Gridbox mean soil nitrogen immobilisation (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``immob_n_pot`` | Soil potential nitrogen immobilisation in each soil pool | cspool,cslayer | +| | and each soil biogeochemistry layer (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``immob_n_pot_gb`` | Gridbox mean potential soil nitrogen immobilisation (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``minl_n_pot`` | Soil potential nitrogen mineralisation in each pool soil pool | cspool,cslayer | +| | and each soil biogeochemistry layer (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``minl_n_pot_gb`` | Gridbox mean potential soil nitrogen mineralisation (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``minl_n`` | Soil nitrogen mineralisation in each pool soil pool | cspool,cslayer | +| | and each soil biogeochemistry layer (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``minl_gb`` | Gridbox mean soil nitrogen mineralisation (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_miner_gb`` | Gribox rate of net mineralisation of soil N (kg m\ :sup:`-2` s\ :sup:`-1`). | | +| | Only available with the ECOSSE soil model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` | | +| | = 3). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_nitrif_gb`` | Gridbox mean rate of nitrification, expressed as N (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_denitrif_gb`` | Gridbox mean rate of denitrification, expressed as N (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n2o_nitrif_gb`` | Gridbox mean N in N\ :sub:`2`\ O lost during nitrification, including partial nitrification | | +| | (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n2o_part_nitrif_gb`` | Gridbox mean N in N\ :sub:`2`\ O lost by partial nitrification (kg m\ :sup:`-2` s\ :sup:`-1`).| | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n2_denitrif_gb`` | Gridbox mean N in N\ :sub:`2` lost from soil during denitrification | | +| | (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n2o_denitrif_gb`` | Gridbox mean N in N\ :sub:`2`\ O lost during denitrification (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n2o_soil_gb`` | Gridbox mean N in N\ :sub:`2`\ O flux from soil to atmosphere (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``no_soil_gb`` | Gridbox mean N in NO flux from soil to atmosphere (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_fertiliser_gb`` | Gridbox nitrogen addition from fertiliser (kg N m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_gas_gb`` | Gridbox mean mineralised nitrogen gas emissions (kg m\ :sup:`-2` (360days)\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_leach`` | Gridbox leached nitrogen loss term (kg N m\ :sup:`-2` s\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ +| ``n_loss`` | Gridbox nitrogen loss term (fixed fraction of n_inorg) (kg N m\ :sup:`-2` | | +| | (360days)\ :sup:`-1`). | | ++-----------------------------+-----------------------------------------------------------------------------------------------+----------------+ + + + +Fire +------------------------------------------------------------------- + +.. tabularcolumns:: |p{4.0cm}|p{9.3cm}|p{2.2cm}| + ++------------------------+------------------------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++========================+====================================================================================+============+ +| Fire indices | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_mcarthur`` | McArthur Forest Fire Danger Index (No units) | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_canadian`` | Canadian Fire Weather Index (No units). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_canadian_ffmc`` | Canadian Fire Weather Index- Fine Fuel Moisture Code (No units). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_canadian_dmc`` | Canadian Fire Weather Index- Duff Moisture Code (No units). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_canadian_dc`` | Canadian Fire Weather Index- Drought Code (No units). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_canadian_isi`` | Canadian Fire Weather Index- Initial Spread Index (No units). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_canadian_bui`` | Canadian Fire Weather Index- Build-up Index (No units). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_nesterov`` | Nesterov Fire Index (No units). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| Burnt area | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``burnt_area`` | PFT burnt area fraction (s\ :sup:`-1`). | npft | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``burnt_area_gb`` | Gridbox mean burnt area fraction (s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| Fire emissions | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``emitted_carbon`` | PFT emitted carbon flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``emitted_carbon_gb`` | Gridbox mean emitted carbon flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``emitted_carbon_DPM`` | Decomposable Plant Material emitted carbon flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``emitted_carbon_RPM`` | Resistant Plant Material emitted carbon flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_CO2_gb`` | Gridbox mean fire CO2 emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_CO2_DPM`` | Decomposable Plant Material fire CO2 emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_CO2_RPM`` | Resistant Plant Material fire CO2 emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_CO_gb`` | Gridbox mean fire CO emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_CO_DPM`` | Decomposable Plant Material fire CO emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_CO_RPM`` | Resistant Plant Material fire CO emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_CH4_gb`` | Gridbox mean fire CH4 emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_CH4_DPM`` | Decomposable Plant Material fire CH4 emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_CH4_RPM`` | Resistant Plant Material fire CH4 emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_NOx_gb`` | Gridbox mean fire NOx emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_NOx_DPM`` | Decomposable Plant Material fire NOx emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_NOx_RPM`` | Resistant Plant Material fire NOx emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_SO2_gb`` | Gridbox mean fire SO2 emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_SO2_DPM`` | Decomposable Plant Material fire SO2 emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_SO2_RPM`` | Resistant Plant Material fire SO2 emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_OC_gb`` | Gridbox mean fire OC emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_OC_DPM`` | Decomposable Plant Material fire OC emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_OC_RPM`` | Resistant Plant Material fire OC emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_BC_gb`` | Gridbox mean fire BC emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_BC_DPM`` | Decomposable Plant Material fire BC emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_BC_RPM`` | Resistant Plant Material fire BC emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_CO2`` | PFT fire CO2 emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_CO`` | PFT fire CO emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_CH4`` | PFT fire CH4 emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_NOx`` | PFT fire NOx emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_SO2`` | PFT fire SO2 emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_OC`` | PFT fire OC emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++------------------------+------------------------------------------------------------------------------------+------------+ +| ``fire_em_BC`` | PFT fire BC emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++------------------------+------------------------------------------------------------------------------------+------------+ + + + +Crops +------------------------------------------------------------------- + +These variables are only available when :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0. + +.. tabularcolumns:: |p{3.5cm}|p{9.8cm}|p{2.2cm}| + ++---------------------+--------------------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++=====================+================================================================================+============+ +| ``croplai`` | Crop PFT leaf area index (LAI). | ncpft | ++---------------------+--------------------------------------------------------------------------------+------------+ +| ``cropcanht`` | Crop PFT canopy height (m). | ncpft | ++---------------------+--------------------------------------------------------------------------------+------------+ +| ``cropleafc`` | Crop PFT carbon in leaf parts (kg m\ :sup:`-2`). | ncpft | ++---------------------+--------------------------------------------------------------------------------+------------+ +| ``cropstemc`` | Crop PFT carbon in stem parts (kg m\ :sup:`-2`). | ncpft | ++---------------------+--------------------------------------------------------------------------------+------------+ +| ``croprootc`` | Crop PFT root carbon pool (kg m\ :sup:`-2`). | ncpft | ++---------------------+--------------------------------------------------------------------------------+------------+ +| ``cropreservec`` | Crop PFT carbon in stem reserve pool (kg m\ :sup:`-2`). | ncpft | ++---------------------+--------------------------------------------------------------------------------+------------+ +| ``cropharvc`` | Crop PFT carbon in harvested parts (kg m\ :sup:`-2`). | ncpft | ++---------------------+--------------------------------------------------------------------------------+------------+ +| ``cropyield`` | Crop PFT yield carbon (kg m\ :sup:`-2`). | ncpft | +| | | | +| | ``cropyield`` is zero in every timestep where there is no harvest, so this | | +| | variable will mostly be used with :nml:mem:`JULES_OUTPUT_PROFILE::output_type` | | +| | set to 'A' or 'X'. | | ++---------------------+--------------------------------------------------------------------------------+------------+ +| ``cropdvi`` | Crop PFT developmental index (DVI). | ncpft | ++---------------------+--------------------------------------------------------------------------------+------------+ +| ``cropsowdate`` | PFT sowing date (1.0 to 365.0). | ncpft | +| | | | +| | If :nml:mem:`JULES_VEGETATION::l_prescsow` = FALSE then this will always be 0. | | ++---------------------+--------------------------------------------------------------------------------+------------+ +| ``harvest_counter`` | 1 in a timestep where crop is harvested, 0 otherwise. | ncpft | +| | | | +| | When used with :nml:mem:`JULES_OUTPUT_PROFILE::output_type` = 'A', will count | | +| | the number of harvests since the beginning of the run. | | ++---------------------+--------------------------------------------------------------------------------+------------+ +| ``harvest_trigger`` | Indicates which condition triggered the harvest: | ncpft | +| | | | +| | 0. No harvest in timestep. | | +| | 1. Crop reached maturity (DVI=2). | | +| | 2. Crop leaf area index became too high (LAI>15). | | +| | 3. Crop has flowered (DVI>1) and temperature in the second soil layer dropped | | +| | below :nml:mem:`JULES_CROPPARM::t_mort_io`. | | +| | 4. Crop has flowered (DVI>1), ``cropharvc`` > 0 and | | +| | (``croprootc`` + ``cropleafc`` + ``cropstemc`` + ``cropreservec``) < | | +| | :nml:mem:`JULES_CROPPARM::initial_carbon_io`. | | +| | 5. :nml:mem:`JULES_VEGETATION::l_prescsow` = T, crop has emerged (DVI>=0), and | | +| | the day of year is the day before the sowing date. | | ++---------------------+--------------------------------------------------------------------------------+------------+ + + + +Trace gas concentrations and fluxes +------------------------------------------------------------------- + +.. tabularcolumns:: |p{3.0cm}|p{10.3cm}|p{2.2cm}| + ++--------------------+-------------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++====================+=========================================================================+============+ +| ``co2_mmr`` | Concentration of atmospheric CO2, expressed as a mass mixing ratio. | | ++--------------------+-------------------------------------------------------------------------+------------+ +| ``flux_o3_stom`` | PFT flux of O3 to stomata (nmol m\ :sup:`-2` s\ :sup:`-1`). | npft | ++--------------------+-------------------------------------------------------------------------+------------+ +| ``o3_exp_fac`` | PFT ozone exposure factor. | npft | ++--------------------+-------------------------------------------------------------------------+------------+ +| ``acetone`` | PFT monoterpene emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++--------------------+-------------------------------------------------------------------------+------------+ +| ``acetone_gb`` | Gridbox mean monoterpene emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++--------------------+-------------------------------------------------------------------------+------------+ +| ``isoprene`` | PFT isoprene emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++--------------------+-------------------------------------------------------------------------+------------+ +| ``isoprene_gb`` | Gridbox mean isoprene emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++--------------------+-------------------------------------------------------------------------+------------+ +| ``methanol`` | PFT methanol emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++--------------------+-------------------------------------------------------------------------+------------+ +| ``methanol_gb`` | Gridbox mean methanol emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++--------------------+-------------------------------------------------------------------------+------------+ +| ``terpene`` | PFT monoterpene emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | npft | ++--------------------+-------------------------------------------------------------------------+------------+ +| ``terpene_gb`` | Gridbox mean monoterpene emission flux (kg m\ :sup:`-2` s\ :sup:`-1`). | | ++--------------------+-------------------------------------------------------------------------+------------+ + + + +Trace gas dry deposition parameters and fluxes +------------------------------------------------------------------- + +.. tabularcolumns:: |p{4.5cm}|p{8.8cm}|p{2.2cm}| + ++---------------------------+--------------------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++===========================+================================================================================+============+ +| ``deposition_ra`` | Aerodynamic resistance (Ra) by surface type (s m\ :sup:`-1`). | ntype | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``deposition_rb`` | Quasi-laminar resistance (Rb) by chemical tracer (s m\ :sup:`-1`). | tracer | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``deposition_rc`` | Surface resistance (Rc) by surface type and chemical tracer (s m\ :sup:`-1`). | ntype, | +| | | tracer | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``deposition_rc_stom`` | Stomatal component of surface resistance (Rc) by surface type and | ntype, | +| | chemical tracer (s m\ :sup:`-1`). | tracer | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``deposition_rc_nonstom`` | Non-stomatal component of surface resistance (Rc) by surface type and | ntype, | +| | chemical tracer (s m\ :sup:`-1`). | tracer | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``deposition_vd`` | Deposition velocity by surface type and chemical tracer (m s\ :sup:`-1`). | ntype, | +| | | tracer | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``deposition_lossrate`` | Deposition loss rate by chemical tracer (s\ :sup:`-1`) | tracer | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``deposition_flux`` | Deposition flux by chemical tracer (kg m\ :sup:`-3` s\ :sup:`-1`) | tracer | +| | | | +| | Only available if :nml:mem:`JULES_DEPOSITION::l_deposition_flux` = TRUE | | +| | | | +| | Requires surface atmospheric concentrations for each deposited species. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ + + + +Water resources +------------------------------------------------------------------- + +These variables are only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_resources` = TRUE. + +.. tabularcolumns:: |p{4.5cm}|p{8.8cm}|p{2.2cm}| + ++---------------------------+--------------------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++===========================+================================================================================+============+ +| ``conv_loss_frac`` | Fraction of abstracted water that is lost during conveyance from source to | | +| | user. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``sfc_water_frac`` | Target for the fraction of demand to be met from surface water. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``demand_rate_domestic`` | Demand rate for water for domestic use (kg s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_domestic` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``demand_rate_industry`` | Demand rate for water for industrial use (kg s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_industry` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``demand_rate_livestock`` | Demand rate for water for livestock use (kg s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_livestock` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``demand_rate_transfers`` | Demand rate for water for transfers (kg s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_transfers` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``water_demand`` | Demand for water across all water resource sectors (kg s\ :sup:`-1`), including| | +| | any allowance for conveyance loss. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``demand_domestic`` | Demand for water for domestic use (kg s\ :sup:`-1`), including any allowance | | +| | for conveyance loss. | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_domestic` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``demand_environment`` | Demand for water for environmental use (kg s\ :sup:`-1`), including any | | +| | allowance for conveyance loss. | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_environment` = TRUE.| | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``demand_industry`` | Demand for water for industrial use (kg s\ :sup:`-1`), including any allowance | | +| | for conveyance loss. | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_industry` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``demand_irrigation`` | Demand for water for irrigation (kg s\ :sup:`-1`), including any allowance for | | +| | conveyance loss. | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_irrigation` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``demand_livestock`` | Demand for water for livestock use (kg s\ :sup:`-1`), including any allowance | | +| | for conveyance loss. | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_livestock` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``demand_transfers`` | Demand for water for transfers (kg s\ :sup:`-1`), including any allowance for | | +| | conveyance loss. | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_transfers` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``water_demand_unmet`` | The part of the total demand for water that is not satisfied (kg s\ :sup:`-1`).| | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``unmet_domestic`` | The part of the demand for water for domestic use that is not satisfied | | +| | (kg s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_domestic` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``unmet_environment`` | The part of the demand for water for domestic use that is not satisfied | | +| | (kg s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_environment` = TRUE.| | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``unmet_industry`` | The part of the demand for water for industrial use that is not satisfied | | +| | (kg s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_industry` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``unmet_irrigation`` | The part of the demand for water for irrigation use that is not satisfied | | +| | (kg s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_irrigation` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``unmet_livestock`` | The part of the demand for water for livestock use that is not satisfied | | +| | (kg s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_livestock` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``unmet_transfers`` | The part of the demand for water for transfers that is not satisfied | | +| | (kg s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_transfers` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``irrig_water`` | Water applied as irrigation (kg m\ :sup:`-2` s\ :sup:`-1`). | | +| | Only available if :nml:mem:`JULES_IRRIG::l_irrig_dmd` = TRUE. | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``gw_avail`` | Groundwater that is available for abstraction at start of timestep (kg) . | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``sw_avail`` | Surface water that is available for abstraction at start of timestep (kg). | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``gw_abstracted`` | Water abstracted from renewable groundwater sources (kg s\ :sup:`-1`). | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``gw_nr_abstracted`` | Water abstracted from non-renewable groundwater sources (kg s\ :sup:`-1`). | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``sw_abstracted`` | Water abstracted from surface water sources (kg s\ :sup:`-1`). | | ++---------------------------+--------------------------------------------------------------------------------+------------+ +| ``water_removed`` | Water that is removed from the system during use (kg s\ :sup:`-1`). | | ++---------------------------+--------------------------------------------------------------------------------+------------+ + + + +Urban +----- + +.. tabularcolumns:: |p{3.5cm}|p{9.8cm}|p{2.2cm}| + ++---------------+-----------------------------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++===============+=========================================================================================+============+ +| ``wrr`` | Urban morphology: Repeating width ratio (or canyon fraction, W/R). | | +| | Calculated if :nml:mem:`JULES_URBAN::l_urban_empirical` = TRUE, | | +| | otherwise it will be the same as the input value (see :ref:`list-of-urban-properties`). | | ++---------------+-----------------------------------------------------------------------------------------+------------+ +| ``hwr`` | Urban morphology: Height-to-width ratio (H/W). See for ``wrr`` above. | | +| | Only used by MORUSES. | | ++---------------+-----------------------------------------------------------------------------------------+------------+ +| ``hgt`` | Urban morphology: Building height (H). See for ``wrr`` above. Only used by MORUSES. | | ++---------------+-----------------------------------------------------------------------------------------+------------+ + + + +IMOGEN +------------------------------------------------------------------- + +.. tabularcolumns:: |p{3.5cm}|p{9.8cm}|p{2.2cm}| + ++----------------------+---------------------------------------------------------------------+------------+ +| Name | Description | Dimensions | ++======================+=====================================================================+============+ +| ``c_emiss_out`` | Prescribed carbon emissions in IMOGEN (Gt / year). | | +| | This is a global value repeated over all land points and is only | | +| | available when IMOGEN is switched on. | | ++----------------------+---------------------------------------------------------------------+------------+ +| ``d_land_atmos_co2`` | Change in atmospheric CO2 concentration from land-atmosphere. | | +| | CO2 feedbacks in IMOGEN (ppm / year). This is a global value | | +| | repeated over all land points and is only available when IMOGEN | | +| | is switched on. | | ++----------------------+---------------------------------------------------------------------+------------+ +| ``d_ocean_atmos`` | Change in atmospheric CO2 concentration from ocean-atmosphere | | +| | CO2 feedbacks in IMOGEN (ppm / year). This is a global value | | +| | repeated over all land points and is only available when IMOGEN is | | +| | switched on. | | ++----------------------+---------------------------------------------------------------------+------------+ + + + + +Grid and indexing variables +------------------------------------------------------------------- + +.. tabularcolumns:: |p{2.5cm}|p{10.8cm}|p{2.2cm}| + ++--------------------+----------------------------------------------------------------------------------------+------------+ +| 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. 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. | | +| | Note that this is defined on the river routing model grid, not on the land point grid. | | ++--------------------+----------------------------------------------------------------------------------------+------------+ +| ``land_index`` | Index (gridbox number) of land points. | | ++--------------------+----------------------------------------------------------------------------------------+------------+ +| ``lice_index`` | Index (gridbox number) of land ice points. | | ++--------------------+----------------------------------------------------------------------------------------+------------+ +| ``soil_index`` | Index (gridbox number) of soil points. | | ++--------------------+----------------------------------------------------------------------------------------+------------+ +| ``tile_index`` | Index (gridbox number) of land points with each surface type. | ntype | ++--------------------+----------------------------------------------------------------------------------------+------------+ + + + +.. |mu| unicode:: μ .. u diff --git a/doc/source/output.rst b/doc/source/output.rst new file mode 100644 index 00000000..46b2a9e2 --- /dev/null +++ b/doc/source/output.rst @@ -0,0 +1,75 @@ +JULES output +============ + + +JULES separates output into one or more output 'profiles'. Within each profile, all variables selected for output are written to the same file with the same frequency (also referred to as the 'output period'). The output period can be any multiple of the model timestep, including calendar months or years. + +Most output is provided on the model grid only. Some variables are provided on the river routing model grid instead. Each output profile can contain **either** model grid **or** river routing model grid variables, but not both. + +Each output file contains the latitude and longitude of each point to allow the points to be located in a grid if desired (e.g. for visualisation). Output files also contain two time related variables to locate the values in time (this is described in more detail `below <#associating-output-values-with-the-correct-time>`_). + +JULES is capable of performing five different types of time-processing - snapshot (instantaneous) values, time averages, time minima, time maxima and time accumulations. Snapshots are instantaneous values produced during the first model timestep of each output period. Time averages, minima, maxima and accumulations are calculated over the output period. Each output variable is annotated with a |cell methods attribute|_ to indicate whether it is a snapshot value (``time : point``), time average (``time : mean``), time minimum (``time : minimum``), time maximum (``time : maximum``) or time accumulation (``time : sum``). + +.. |cell methods attribute| replace:: CF convention ``cell_methods`` attribute +.. _cell methods attribute: http://cfconventions.org/Data/cf-conventions/cf-conventions-1.6/build/cf-conventions.html#cell-methods + + +Each profile can be considered as a separate data stream. By using more than one profile the user can, for example: + +* Output one set of variables to one file, and other variables to another file. +* Write instantaneous values to one file, and time-averaged values to another. +* Write low-frequency output throughout the run to one file, and high-frequency output from a smaller part of the run (e.g. a 'special observation period') to another file. + +All output files will be NetCDF if JULES is compiled with 'proper' NetCDF libraries (see :doc:`/building-and-running/intro`). Otherwise all output will be in columnar ASCII files. + + +Associating output values with the correct time +----------------------------------------------- + +JULES output files contain two time related variables to allow model output to be associated with the correct model time: + +``time`` + For each output period, this variable contains the time of the end of the output period. This is the time that any snapshot values apply at. + +``time_bounds`` + For each output period, this variable contains two values - the start and end of the output period. The output period is then the half-open interval given by: + + .. code-block:: fortran + + time_bounds(1) < time <= time_bounds(2) + + This is the interval that means, minima, maxima and accumulations are calculated over. + +During each model timestep, JULES captures values for output at the end of the timestep (i.e. after all the science code). This means that in output files, snapshot data at a particular timestep is: + +* The state of the model at the end of the model timestep. +* The fluxes that produced that state over the model timestep. + +Due to the way the model equations work, this ensures that all output at a given timestep in the output files is consistent. + + +.. _initial_data: + +Initial data +------------ + +With the formulation given above, the initial state of the model (i.e. the state at the beginning of the first timestep of a section) is never output (except to dump files). For the majority of users, this will not be an issue. If the initial state is required, it is possible for an output profile to output the initial state for each section of a run (i.e. initial state of each spinup cycle and the main run) to a separate file - see :nml:mem:`JULES_OUTPUT_PROFILE::output_initial`. + +.. warning:: + In initial data files, **only snapshot values for state variables will be valid**. All other variables specified in the output profile will exist in the file, but their values will be garbage - *not necessarily NAN* - so use these files with caution. + + +Dump files +---------- + +JULES writes dump files (a snapshot of the current model state) at several points during a run. These can be used to restart the model from that point if desired. The times that dump files are written are: + +* After initialisation is complete, immediately before the start of the run (initial state). +* Before starting each cycle of spin-up. +* Before starting the main run. +* At the end of the run (final state). +* At the start of each calendar year. + +Each dump is marked with the model date and time that it was produced. + +Prior to vn4.3, the dump file contained sufficient prognostic variables such that the pre-dump model state could be recreated. From vn 4.3 onwards, the dump file now includes ancillary data. The model can optionally restart from these data rather than the values given in the ancillaries namelists. Latitude and longitude information are also now written to (but not read from) the dump file to aid users wishing to interrogate dump files for debugging or other purposes. diff --git a/doc/source/overview/intro.rst b/doc/source/overview/intro.rst new file mode 100644 index 00000000..28445775 --- /dev/null +++ b/doc/source/overview/intro.rst @@ -0,0 +1,8 @@ +Overview of JULES +================= + +This section provides a brief overview of JULES and an introduction to some of the key switches that determine what the model will simulate in a given run. + +.. toctree:: + overview + key-switches diff --git a/doc/source/overview/key-switches.rst b/doc/source/overview/key-switches.rst new file mode 100644 index 00000000..1981aba4 --- /dev/null +++ b/doc/source/overview/key-switches.rst @@ -0,0 +1,18 @@ +Some key switches +================= + +There are many variables that act together to determine how a run of JULES is set up and these are covered in detail in :doc:`/namelists/contents`. Additionally, `configurations `__ illustrate suitable combinations of options. Here we highlight a few key switches that select broad areas of science, particularly for the benefit of new users. + +The phenology model for natural vegetation can be enabled using :nml:mem:`JULES_VEGETATION::l_phenol` which uses the leaf turnover rate to calculate a time-varying Leaf Area Index (LAI). + +To simulate carbon stocks in natural vegetation, the TRIFFID dynamic vegetation model can be enabled via the switch :nml:mem:`JULES_VEGETATION::l_triffid`. When TRIFFID is on, competition between tiles is switched on with :nml:mem:`JULES_VEGETATION::l_veg_compete` and the effect of nitrogen on vegetation growth is enabled via :nml:mem:`JULES_VEGETATION::l_nitrogen`. + +The crop model, which is simulates phenology and carbon stocks in crops, can be switched on by setting the number of crop tiles :nml:mem:`JULES_SURFACE_TYPES::ncpft` to a non-zero value. + +The crop model and TRIFFID cannot currently be used together. To simulate agricultural areas within TRIFFID, a fraction of the gridbox can be reserved for agricultural Plant Functional Types (PFTs) (as defined by :nml:mem:`JULES_TRIFFID::crop_io` > 0). Agricultural PFT competition and a representation of harvest carbon can be switched on with :nml:mem:`JULES_VEGETATION::l_trif_crop`. + +If neither the phenology model nor the crop model are used, LAI for each vegetation tile can be set to a constant (:nml:mem:`JULES_PFTPARM::lai_io`) or a time series or seasonal cycle can be prescribed (:nml:lst:`JULES_PRESCRIBED`). + +To simulate carbon and nitrogen stocks in the soil, the 4-pool model should be selected by setting :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2. This option adds prognostic soil pools and must be used with the TRIFFID vegetation model. If TRIFFID is not used, prescribed soil pools must be invoked via :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 1. Layered soil pools are used if :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = .TRUE.. + +A multi-layer snow model can be selected using :nml:mem:`JULES_SNOW::nsmax`. Parameterisations of surface and subsurface runoff generation are controlled using :nml:mem:`JULES_HYDROLOGY::l_top` and :nml:mem:`JULES_HYDROLOGY::l_pdm`, while the routing of water in rivers uses :nml:mem:`JULES_RIVERS::l_rivers`. diff --git a/doc/source/overview/overview.rst b/doc/source/overview/overview.rst new file mode 100644 index 00000000..898f6667 --- /dev/null +++ b/doc/source/overview/overview.rst @@ -0,0 +1,11 @@ +Overview +======== + +This section provides a brief overview of JULES, largely so as to provide background information and introduce terms used in the rest of the manual. Further details can be found at the `JULES website `_ and in the two `JULES description papers `_ (Best et al., 2011, GMD and Clark et al., 2011, GMD). + +For both gridded and single point runs, JULES views each gridbox as consisting of a number of surface types. The fractional area of each surface type is either prescribed by the user or modelled by the TRIFFID sub-model. Each surface type is represented by a surface tile, and a separate energy balance is calculated for each surface tile. The gridbox average energy balance is found by weighting the values from each surface tile. In its standard form, JULES recognises nine surface types: broadleaf trees, needleleaf trees, C3 (temperate) grass, C4 (tropical) grass, shrubs, urban, inland water, bare soil and ice. These 9 types are modelled as 9 surface tiles. A land gridbox is either any mixture of the first 8 surface types, or is land ice. Note that, from version 2.0, one is not limited to these 9 standard surface types (unless running TRIFFID). + +Soil processes are modelled in several layers. Each surface tile can be associated with its own soil tile, or all surface tiles can interact with a shared soil column. Each gridbox requires meteorological driving variables (such as air temperature) and variables that describe the soil properties at that location. It is also possible to prescribe certain characteristics of the vegetation, such as Leaf Area Index, to vary between gridboxes. + +JULES can be run for any number of gridboxes from one upwards. The number of gridboxes is limited by the availability of computing power and suitable input data. When run on a grid, JULES models the average state of the land surface within the area of the gridbox and most quantities are taken to be homogeneous within the gridbox (with options to include subgrid-scale variability of a few, such as rainfall). In that case, the input data are also area averages. JULES can also be run "at a point", with inputs that are taken to represent conditions at that point - this configuration might be used when field measurements of meteorological conditions are available. + diff --git a/doc/source/release_notes/JULES1-0.rst b/doc/source/release_notes/JULES1-0.rst new file mode 100644 index 00000000..2f07c141 --- /dev/null +++ b/doc/source/release_notes/JULES1-0.rst @@ -0,0 +1,4 @@ +JULES version 1.0 +================= + +Initial public release of the JULES code. JULES v1.0 will only run for a single point and only supports ASCII data. diff --git a/doc/source/release_notes/JULES2-0.rst b/doc/source/release_notes/JULES2-0.rst new file mode 100644 index 00000000..3c471435 --- /dev/null +++ b/doc/source/release_notes/JULES2-0.rst @@ -0,0 +1,12 @@ +JULES version 2.0 Release Notes +=============================== + +The physical processes and their representation in version 2.0 have not changed from version 1. However, version 2.0 is much more flexible in terms of input and output, and allows JULES to be run on a grid of points. New features include: + +* Ability to run on a grid. +* Choice of ASCII or binary formats for input and output files (also limited support of NetCDF input). +* More flexible surface types - number and types can vary. +* Optional time-varying, prescribed vegetation properties. +* More choice of meteorological input variables. +* Optional automatic spin-up. +* Enhanced diagnostics - large choice of variables, frequency of output, sampling frequency, etc. diff --git a/doc/source/release_notes/JULES2-1.rst b/doc/source/release_notes/JULES2-1.rst new file mode 100644 index 00000000..757ab2fb --- /dev/null +++ b/doc/source/release_notes/JULES2-1.rst @@ -0,0 +1,26 @@ +JULES version 2.1 Release Notes +=============================== + +Versions 2.1.1 and 2.1.2 were released to fix major bugs found in v2.1 - they contain no new features. + +Version 2.1 of JULES includes extensive modifications to the descriptions of the processes and to the control-level code (such as input and output). These are covered briefly below. Several bug fixes and minor changes to make the code more robust have also been applied. All files are now technically FORTRAN90 (.f90) although many are simply reformatted FORTRAN77 files in which continuation lines are now indicated by the use of the '&' character. + + +Process descriptions +-------------------- + +The main change is that a new multi-layer snow scheme is available. This scheme was developed by Richard Essery at the University of Edinburgh and co-workers. At the time of writing there is little scientific documentation of this development, but this will be made available as soon as possible. In brief, the older, simple scheme represents the snowpack as a single layer with prescribed properties such as density, whereas the new scheme has a variable number of layers according to the depth of snow present, and each layer has prognostic temperature, density, grain size, and solid and liquid water content. The new scheme reverts to the previous, simpler scheme if ``nsmax = 0`` or when the snowpack becomes very thin. + +A four-pool soil carbon model based on the RothC model now replaces the single pool model when dynamic vegetation (TRIFFID) is selected. + +There have been several major changes that most users will not notice or need be concerned about. These include a change in the linearization procedure that is used in the calculation of surface energy fluxes (described in the technical documentation). A standard interface is now used to calculate fluxes over land, sea and sea ice. Each surface tile now has an elevation relative to the gridbox mean. + +These changes mean that, even with the new snow scheme switched off (``nsmax=0``), results from v2.1 will generally not be identical to those from v2.0. + + +Control-level code +------------------ + +The major change at v2.1 to the control-level code is that NetCDF output is now supported. Both diagnostic and restart files (dumps) can be in NetCDF format. There have been several changes to the run control file, partly to reflect new science but also in an attempt to organise the file better. These changes mean that run control and restart files from JULES v2.0 are not compatible with v2.1 (although they could be reformatted without too much difficulty). + +Finally, since JULESvn1.0 the MOSES and JULES code bases have been evolving separately, but with JULES v2.1 these differences have been reconciled with the UM. diff --git a/doc/source/release_notes/JULES2-2.rst b/doc/source/release_notes/JULES2-2.rst new file mode 100644 index 00000000..65a42f56 --- /dev/null +++ b/doc/source/release_notes/JULES2-2.rst @@ -0,0 +1,13 @@ +JULES version 2.2 Release Notes +=============================== + +Along with fixes for known bugs, the changes made for version 2.2 mostly consist of several small additions to the science code. Changes to the control code have mostly been limited to bug-fixes. + +* New options for treatment of urban tiles - inclusion of the Met Office Reading Urban Surface Exchange Scheme (MORUSES) and a simple two tile urban scheme. +* Effects of ozone damage on stomata from Stephen Sitch at the University of Leeds. +* New treatment of direct/diffuse radiation in the canopy from Lina Mercado at CEH. +* A new switch allows the competing vegetation portion of TRIFFID to be switched on and off independently of the rest of TRIFFID (i.e. it is now possible to use the RothC soil carbon without having changing vegetation fractions). + +There have also been changes made to the way JULES is compiled, due to the re-integration with the Met Office Unified Model (UM). The UM uses preprocessor directives to compile different versions of routines depending on the selected science options. For compatibility with this system, JULES will now require a compiler with a preprocessor. This should not be noticed by the majority of users - most modern compilers include a preprocessor and the Makefile deals with setting up the appropriate preprocessor options. + +Finally, JULES was added to the UM code repository as a mirror of the JULES repository at (UM version vn7.5, JULES vn2.2). diff --git a/doc/source/release_notes/JULES3-0.rst b/doc/source/release_notes/JULES3-0.rst new file mode 100644 index 00000000..a32b968c --- /dev/null +++ b/doc/source/release_notes/JULES3-0.rst @@ -0,0 +1,18 @@ +JULES version 3.0 Release Notes +=============================== + + +The major change in version 3.0 is the introduction of the IMOGEN impacts tool. IMOGEN is a system where JULES is gridded on to surface land points, and is forced with an emulation of climate change using "pattern-scaling" calibrated against the Hadley Centre GCM. This climate change impacts system has the advantage that: + +* The pattern-scaling allows estimates of climate change for a broad range of emissions scenarios. +* New process understanding can be tested for its global implications. +* New process understanding can also be checked for stability before full inclusion in a GCM. +* By adding climate change anomalies to datasets such as the CRU dataset, then GCM biases can be removed. + +It must be recognised that the system is "off-line", and so if major changes to the land surface occur there might be local and regional feedbacks that can only be predicted using a fully coupled GCM. Hence IMOGEN doesn't replace GCMs, but it does give a very powerful first-look as to potential land surface changes in an anthropogenically forced varying climate. This was accomplished with help from Mark Lomas at the University of Sheffield and Chris Huntingford at CEH. + +There are also several small bug fixes: + +* A fix effecting fluxes in `sf_stom` from Lina Mercado at CEH. This bug fix was announced on the mailing list. +* Small fixes for potential evaporation and canopy snow depth from the UM. +* A small issue with some memory not being deallocated at the end of a run. diff --git a/doc/source/release_notes/JULES3-1.rst b/doc/source/release_notes/JULES3-1.rst new file mode 100644 index 00000000..52288505 --- /dev/null +++ b/doc/source/release_notes/JULES3-1.rst @@ -0,0 +1,36 @@ +JULES version 3.1 Release Notes +=============================== + + +JULES version 3.1 sees little change to the science of JULES, but contains several major developments intended to make development easier going forward. + + +Restructuring of the code +------------------------- + +The directory structure of the JULES code has been changed to be more logical and allow for a cleaner separation between control, initialisation, I/O and science code. This includes the introduction of directories containing UM-specific code for initialisation in the UM. This was done as part of the work to completely remove (MOSES and) JULES code from the UM code repository - it now sits in its own repository. + + +New I/O framework +----------------- + +The input and output code has been completely revamped in order to modularise and simplify the code. It allows for data to be input on any timestep and interpolated down to the model timestep. Support for outputting of means and accumulations remains. NetCDF is now the only supported binary format (although it should be relatively simple to write drivers for other output formats if desired), and ASCII files are allowed for data at a single location only. Support for the GrADS flat binary format has been dropped, although the NetCDF output should be usable with GrADS with very little work. + + +User Interface changes +---------------------- + +The user interface also sees significant changes. The monolithic .jin run control file has been replaced by several smaller files containing Fortran namelists for input of options and parameters. This is more consistent with the UM, and offers the opportunity to adapt UM tools to provide a GUI for running JULES in the future. + + +Other changes +------------- + +There are several not-insignificant changes to the science code: + +* Structures are now used for dimensioning variables - this allows for more flexibility of grids than the old system of row_length/rows and halos. +* Move to a new implicit solver - ``sf_impl2`` is now used rather than ``sf_impl`` for consistency with the UM. However, the way the implicit coupling is set up means it operates in a similar way to the old scheme. +* A change in the way fresh snow is handled in the multi-layer snow scheme - the density of fresh snow is now prescribed by a new variable (``rho_snow_fresh``). Suggested by Cécile Ménard and implemented by Doug Clark. +* Bug fix from Doug Clark for the multi-layer snow scheme that fixes problems with the model oscillating between 0 and 1 snow layers every timestep, preventing snow melt. +* Changes to the sea-ice surface exchange when operating as part of the UM. This will not affect the majority of users. +* Slight changes to the coupling between the explicit and implicit schemes. The vast majority of users will not need to worry about this. diff --git a/doc/source/release_notes/JULES3-2.rst b/doc/source/release_notes/JULES3-2.rst new file mode 100644 index 00000000..abdc58a7 --- /dev/null +++ b/doc/source/release_notes/JULES3-2.rst @@ -0,0 +1,49 @@ +JULES version 3.2 Release Notes +=============================== + + +JULES version 3.2 sees several enhancements and bug fixes in both the science and control code. + + +Standard Configurations +----------------------- + +A set of standard science configurations have been defined. These are based on well tested operational Met Office models, and are intended to cover a wide range of use cases. + + +Improvements to output +---------------------- + +In JULES version 3.1, under some circumstances, it was not entirely clear how the timestamps in output files applied to the values. This has been thoroughly addressed in version 3.2. + +Changes have also been made to the attributes of output variables: + +* The units attribute for output variables has been updated to be compliant with `UDUNITS2 `_. +* A `CF conventions `_ coordinates attribute has been added to all output variables that explicitly links the latitude and longitude to the data. + + +Biogenic Volatile Organic Compound (BVOC) emissions +--------------------------------------------------- + +Code written by Federica Pacifico for isoprene emissions has been implemented and extended to include monoterpene, acetone and methanol emissions. This addition is purely diagnostic in the standalone model (i.e. provides new output variables, but has no feedbacks), but will allow the UM to implement interactive BVOC emissions (i.e. with feedbacks) in the future. + +A paper has been written describing and evaluating the isoprene emission scheme - Pacifico et. al., 2011. Atmos. Chem. and Phys., 11, 4371-4389 (`PDF `_). + + +Alternative build system +------------------------ + +It is now possible to build JULES using FCM make. FCM is a set of tools developed by the Met Office for managing and building source code, with a particular focus on making it easy to build large Fortran programs (such as JULES). FCM is open source software, and can be downloaded for free from `Github `_. + + +Bugs fixed +---------- + +* Array bounds error with ``SICE_INDEX_NCAT``. +* Incorrect usage of ``COR_MO_ITER``. +* Monthly/yearly output files not rolling over properly on certain configurations of GFortran. +* A collection of small memory leaks. +* Not able to read or write ASCII dumps with the new snow scheme on. +* Use fixed dimension names for output files (rather than using those given for input files). +* Using ``can_rad_mod = 5`` causes night-time dark respiration to be 0 under certain circumstances. + diff --git a/doc/source/release_notes/JULES3-3.rst b/doc/source/release_notes/JULES3-3.rst new file mode 100644 index 00000000..210e4434 --- /dev/null +++ b/doc/source/release_notes/JULES3-3.rst @@ -0,0 +1,60 @@ +JULES version 3.3 Release Notes +=============================== + + +Ability to run JULES in parallel +-------------------------------- + +JULES can now run multiple points in parallel, using multiple cores on the same machine or a cluster of machines. This is accomplished using `MPI (Message Passing Interface) `_, a standardised message passing interface. Several implementations of MPI are available, the most commonly used being `MPICH2 `_ and `OpenMPI `_. + +JULES takes advantage of the parallel I/O features in `HDF5 `_ / `NetCDF4 `_. These are not enabled by default, and so must be explicitly enabled when HDF5 / NetCDF4 are compiled. More information on how to do this can be found on the `NetCDF website `_. + +Information on how to build and run JULES in parallel can be found in the JULES User Guide. *Note that although this development has proven stable during testing, it is still experimental and is considered to be for advanced users only.* + + +Changes to documentation +------------------------ + +From a users point of view, the most important change is that the JULES documentation and coding standards are now provided in two forms - HTML (this is the preferred format) and PDF. The HTML documentation is also available on the web at ``_. + +This has been made possible by migrating the documentation from a single massive Word document to the `Sphinx `_ documentation generator (with some custom extensions to better support Fortran namelists). Although originally intended to document Python projects, Sphinx's extensibility has seen it adopted for a wide range of projects. Using Sphinx has several advantages over the previous monolithic Word document: + +* Both forms of documentation (HTML and PDF) can be built from the same sources. +* The documentation is now split into several smaller files that are combined by Sphinx at build-time, leading to increased readability. +* `reStructuredText `_, the markup language used by Sphinx, is a plain text format, meaning that it can be version controlled much more effectively than a Word document (which is treated by Subversion as a single binary entity). +* The only software required to update the documentation is your favourite text editor (rather than Word). + +The `JULES repository on PUMA `_ has also been refactored so that configurations, documentation and examples sit in a separate project to the core Fortran code. + + +Other changes +--------------- + +Disambiguation of sea ice roughness lengths for heat and momentum + Prior to vn3.3, these were implicitly assumed to be equal by the code. They can now be set separately in the namelist ``JULES_SURF_PARAM``. + +Improvements to the numerics in the soil hydrology + Previously, the soil hydrology scheme coped poorly with significant gradients in soil moisture because of the sensitive dependence of the hydraulic conductivity and soil water suction on the soil moisture. See the new switch ``l_dpsids_dsdz``. + +Implicit numerics for land ice + Previously, the updating of land ice temperatures was always explicit, limiting the thickness of soil levels that can be used with standard time steps. There is now an option for implicit numerics for land ice - see the new switch ``l_land_ice_imp``. + +Scaling of land surface albedo to agree with a given input + An option has been added to prescribe the grid-box mean snow-free albedo to a given input (e.g. observations, climatology). See the new switch ``l_albedo_obs``. For SW albedos, the albedos of the individual tiles are scaled linearly so that the grid-box mean albedo matches the observations, within limits for each tile. When VIS and NIR albedos are required then the input parameters are scaled and corrected in a similar manner. The change was included in the Global Land configuration at vn5.0: https://code.metoffice.gov.uk/trac/GL/ticket/8. + +BVOC emissions now on a switch + Previously, BVOC emissions diagnostics were calculated all the time, regardless of whether they were output. A new switch - ``l_bvoc_emis`` - has been added to enable the calculation of these diagnostics only when required. + +Improvements to logging + A new namelist file - ``logging.nml`` - has been added to give more control over log output from JULES. Previously all output was directed to ``stdout``. + +Specify namelist directory as an argument + It is now possible to specify the directory containing the namelist files as a command line argument to JULES. If no argument is given, JULES looks for the namelist files in the current working directory. Previously, JULES had to be executed in the directory containing the namelists - this change should make it easier to run JULES in batch mode. + + +Bugs fixed +---------- + +* Initialisation of ``chr1p5m`` and ``resfs`` in ``sf_exch``. +* Fix for potential divide-by-zero in ``sf_stom`` when running with ``can_rad_mod = 1``. +* Various UM-related fixes not relevant to standalone JULES (ENDGAME, aerosol deposition scheme, etc.). diff --git a/doc/source/release_notes/JULES3-4.rst b/doc/source/release_notes/JULES3-4.rst new file mode 100644 index 00000000..a1651987 --- /dev/null +++ b/doc/source/release_notes/JULES3-4.rst @@ -0,0 +1,49 @@ +JULES version 3.4 Release Notes +=============================== + + +n.b. A critical memory leak was found in JULES v3.4 that necessitated a new release, designated v3.4.1. + + +Changes to semantics of output +------------------------------ + +The output semantics used since JULES vn3.2 (i.e. state variables captured at the start of a timestep, flux variables captured at the end) were confusing some users. The semi-implicit scheme in JULES is designed so that the state and fluxes at the end of a timestep are consistent with each other, but under the previous semantics these were staggered by one timestep in output files. + +All variables are now captured at the end of a timestep, so state and flux variables at a particular timestep in output files will be consistent with each other. A new option has been added to request the output of initial state, however very few users will have a use for this. It is still the case that the value in the ``time`` variable can be used to place snapshot data in time, and the values in ``time_bounds`` represent the interval over which a mean or accumulation applies. + +More details can be found at :doc:`/output`. + + +Input and/or output of variables with multiple 'levels' dimensions has been improved +------------------------------------------------------------------------------------ + +In previous versions of JULES since vn3.1, variables could only be input or output with a single 'levels' dimension. In particular, this caused problems with variables in the new snow scheme, which have two 'levels' dimensions on top of the grid dimensions (tiles and snow levels). This led to compromises being made with the snow layer variables: + +* It was only possible to initialise the snow layer variables using a constant value, from a previous dump or using :nml:mem:`JULES_INITIAL::total_snow` +* In output files, the snow layer variables were represented using a separate variable for each tile + +This problem is solved in JULES vn3.4 - it is now possible to input and output variables with multiple 'levels' dimensions (there is not even a restriction to two 'levels' dimensions). This means that both compromises for snow layer variables detailed above have been removed. + + +Streamlined process for adding new variables for input and/or output +-------------------------------------------------------------------- + +Although fairly simple, the process for adding a new variable for input and/or output in JULES vn3.1 - vn3.3 required several edits to be made, and hence provided many opportunities to make mistakes. This process is simplified in JULES vn3.4 to require fewer edits. More details can be found at :ref:`implementing-new-variables-for-input-and-output`. + + +Other changes +--------------- + +Tidying of boundary layer code + Some small changes have been made to tidy up some of the boundary layer code (i.e. routines in ``src/science/surface``) - this is mostly removing unused variables and tidying up subroutine argument lists. + +OpenMP related changes + Some `OpenMP `_ directives have been added to certain loops. OpenMP is a form of shared-memory parallelism in which the user inserts directives (specially formatted code comments) providing information that allows the compiler to parallelise sections of code (in particular loops) without worrying about corrupting data. It is used in the UM, but is currently not enabled when compiling JULES standalone. + + +Bugs fixed +---------- + +* Output (including dump files) not correctly generated for the last spin-up cycle when spin-up fails and :nml:mem:`JULES_SPINUP::terminate_on_spinup_fail` = TRUE +* ``lw_net`` diagnostic does not include the contribution from the reflected incoming longwave if the emissivity is less than zero diff --git a/doc/source/release_notes/JULES4-0.rst b/doc/source/release_notes/JULES4-0.rst new file mode 100644 index 00000000..274ef731 --- /dev/null +++ b/doc/source/release_notes/JULES4-0.rst @@ -0,0 +1,59 @@ +JULES version 4.0 Release Notes +=============================== + + +JULES-Crop crop model +--------------------- + +JULES vn4.0 sees the introduction of the JULES-Crop crop model. This has been the result of many years of hard work from Tom Osbourne et. al. at the `University of Reading `_. + +A lot of the work done in getting it ready for the trunk and testing was done in the Met Office by Karina Williams and Jemma Gornall. + + +Daily disaggregator for forcing data +------------------------------------ + +JULES can now be driven with daily forcing data, and the daily disaggregator will disaggregate the daily forcing down onto the model timestep. + +For more information, see :nml:mem:`JULES_DRIVE::l_daily_disagg`. + + +Major namelist changes +---------------------- + +JULES vn4.0 also sees a major revamp of the science-related namelists. The monolithic JULES_SWITCHES namelist, and various others, are gone, and have been replaced with science section namelists. For more details, see :doc:`/namelists/contents`. + +This has been with the aim of providing a GUI for editing the JULES namelists using `Rose `_, which is now available - see :doc:`/building-and-running/rose`. + +It also has the advantage that the new namelists are cut-and-paste-able between the UM and JULES, which should make it easier to ensure that the same science is being used in online and offline runs. + + +Removal of GNU make build files +------------------------------- + +After a period of supporting two build systems (FCM make and GNU make), it has been decided that support for GNU make should be removed. The overhead of maintaining two build systems was getting too large, and FCM make is preferred for several reasons: + +Directory structure + * The directory level dependencies used by the JULES Makefile to ensure files are compiled in the correct order forced the directory structure to adapt to it. + * FCM make does automatic dependency analysis for each file to ensure they are compiled in the correct order, meaning the directory structure doesn't have to be compromised to keep the build system happy. + +Dependencies + * The JULES GNU Makefiles required that dependencies be manually maintained, both in terms of the order of sub-makes and actual file dependencies within the sub-makes. + * FCM make automatically detects all dependencies and does things in the correct order. + +Parallel builds + * JULES builds with GNU make could not be parallelised, because of the use of directory level sub-makes. + * FCM make considers each individual file, so builds can be parallelised. + +Integration with Rose + * FCM make has good integration with Rose, allowing the Rose GUI for JULES to configure and run builds as well as the namelists. + + +Bugs and other changes +---------------------- + +* Output for land points not comparing between land_only = T and F runs with 2D grid +* Incorrect behaviour when ``spinup_end`` == ``data_end`` +* Fixed overflow problem with ``datetime_diff`` when ``datetime``\ s are too far apart +* Removed old implicit solver and ltimer code +* Unified management of printing and error reporting for UM and standalone diff --git a/doc/source/release_notes/JULES4-1.rst b/doc/source/release_notes/JULES4-1.rst new file mode 100644 index 00000000..c025cae0 --- /dev/null +++ b/doc/source/release_notes/JULES4-1.rst @@ -0,0 +1,56 @@ +JULES version 4.1 Release Notes +=============================== + + +Irrigation demand +----------------- + +When enabled, irrigation demand adds water to the soil moisture up to the critical point, meaning that vegetation does not experience water stress. At the moment the amount of water added is not limited, although it will be limited in a future version. + +There are two schemes that can be used to determine when to irrigate: + +1. This method calculates optimum planting dates for non-rice crops using averages from driving data and so requires at least one year of driving data. It was written by Nic Gedney and is based on the crop calendar from Doell & Siebert (2002). +2. Uses development index (dvi) across all tiles from JULES-crop (written by Rutger Dankers). Maximum dvi must exceed -1 (indicates sowing) for irrigation to occur. + +See the documentation for :nml:mem:`JULES_IRRIG::l_irrig_dmd` for more details. + + +Carbon cycle developments +------------------------- + +A number of carbon cycle developments are included in this release: + +#. Changes to the competition code to allow for flexible, height-based competition in TRIFFID. See :nml:mem:`JULES_VEGETATION::l_ht_compete`. +#. Trait-based plant physiology that allows the plant physiology to be defined by parameters that are more readily definable from observations. See :nml:mem:`JULES_VEGETATION::l_trait_phys`. +#. Code for simulating land-use change (e.g. forest clearance) including product pools (previously implemented in HadGEM2-ES). See :nml:mem:`JULES_VEGETATION::l_landuse`. +#. Time-varying agricultural fraction now officially supported. Time-varying CO2 concentration is also supported with some caveats. See :ref:`the list of supported prescribed data variables `. +#. Switch to enable/disable the adjustment of fractions during initialisation. See :nml:mem:`JULES_VEGETATION::l_recon`. + + +Maximum and minimum output types +-------------------------------- + +It is now possible to output the maximum and minimum value over the output period of any variable, e.g. monthly maximum. + +See :nml:mem:`JULES_OUTPUT_PROFILE::output_type` for more information. + + +Changes to the coupling routines +-------------------------------- + +The routines that couple the JULES science to the UM and to the standalone wrapper have changed - see ``src/control/standalone/control.F90``. + +This is mainly in order to simplify the coupling with the UM and to facilitate upcoming developments. + + +Bugs and other changes +---------------------- + +* It is now possible to run with a fixed 365-day calender (i.e. no leap years) using the :nml:mem:`JULES_TIME::l_leap` flag. +* Corrected temperature limitation on soil respiration to be consistent with HadGEM2-ES. +* Minor tweaks to the crop model. +* Improvements to the BVOC emissions model, including linking with UKCA via the UM for coupled studies. +* Changes to introduce the COARE algorithm for surface exchange over the ocean. +* Improved error messages for I/O errors (e.g. namelist reading) +* Fixed a bug where the start and end time of data are not initialised correctly when using the daily disaggregator. +* Fixed a bug in tilepts caused by the use of short-circuiting logic that is not supported by some compilers. diff --git a/doc/source/release_notes/JULES4-2.rst b/doc/source/release_notes/JULES4-2.rst new file mode 100644 index 00000000..228948a8 --- /dev/null +++ b/doc/source/release_notes/JULES4-2.rst @@ -0,0 +1,48 @@ +JULES version 4.2 Release Notes +=============================== + + +JULES version 4.2 is the first release where all development has taken place in the Met Office collaboration repository. On the whole, this has been a success, with module leaders beginning to use the Trac system to track and approve developments in their areas. + +The JULES vn4.2 release consists of 35 tickets from 13 authors across 39 commits. + + +Science changes +--------------- + +* TRIP and RFM river routing (see :doc:`/namelists/jules_rivers.nml`) +* Incorporation of widely used fire risk indices (see :doc:`/namelists/fire.nml`) +* New soil thermal conductivity model that is more appropriate for organic soils (see :nml:mem:`JULES_SOIL::soilhc_method`) +* Addition of "bedrock" column beneath the soil column, in which only thermal diffusion occurs (see :nml:mem:`JULES_SOIL::l_bedrock`) +* New canopy radiation scheme in which the nitrogen follows an exponential decay (see :nml:mem:`JULES_VEGETATION::can_rad_mod`) +* Updates to trait PFTs (see :nml:mem:`JULES_VEGETATION::l_trait_phys`) to ensure that the dynamic and equilibrium solutions for vegetation fraction are equivalent +* Crop model now conserves carbon + + +Technical changes +----------------- + +* Added flag to force the model grid to be 1D (see :nml:mem:`JULES_MODEL_GRID::force_1d_grid`) +* Several new diagnostics added (see :doc:`/output-variables`) +* New rose-stem regression tests added +* All rose-stem tests migrated to use NetCDF and ``nccmp`` +* Retirement of several include files +* Removal of logging namelist - output location should now be controlled using pipes (i.e. ``1>/my/file 2>&1``) or features of your ``mpiexec`` or ``mpirun`` program +* Additional consolidation of shared (i.e. standalone and UM) control and initialisation routines +* Optimisation of ``sf_stom`` and ``leaf_limits``, resulting in ~20% speedup for :nml:mem:`JULES_VEGETATION::can_rad_mod` = 4 + + +Bugs fixed +---------- + +* Bug in calculation of ``n_leaf`` and ``n_stem`` in ``sf_stom`` +* Memory overwriting bug in TRIFFID +* Differing error message lengths in UM +* ``hcons`` now passed to the snow scheme instead of ``hcon(:,0)`` +* Several bug fixes for IMOGEN +* Patch to enable collective access for parallel NetCDF in NetCDF 4.2 onwards +* ``soil_hyd`` now declares ``ksz`` correctly (i.e. ``ksz(npnts,0:nshyd)`` instead of ``ksz(npnts,nshyd)``) - this only affects runs where the soil properties vary for each layer +* Correction to the accumulation of ``g_leaf_phen`` in-between calls to TRIFFID + + +Full details of the tickets committed for JULES vn4.2 can be found on the `collaboration repository Trac system `_. diff --git a/doc/source/release_notes/JULES4-3.rst b/doc/source/release_notes/JULES4-3.rst new file mode 100644 index 00000000..6c625f70 --- /dev/null +++ b/doc/source/release_notes/JULES4-3.rst @@ -0,0 +1,57 @@ +JULES version 4.3 Release Notes +=============================== + + +The JULES vn4.3 release consists of 36 tickets from 18 authors across 39 commits. + +Full details of the tickets committed for JULES vn4.3 can be found on the `JULES shared repository Trac system `_. + + +Science changes +--------------- + +* Enhancements to the multi-layer snow scheme for GL7.0 (Global Land configuration, version 7.0) + + * Addition of ET metamorphism + * Infiltration of rain water into the snow pack + * Albedo of snow and relationship to plant canopies + +* Generalisation of the crop scheme to work with trait-based plant physiology and BVOC emissions +* Update to wetland scheme (see :nml:mem:`JULES_HYDROLOGY::l_wetland_unfrozen`) +* River routing updates to allow RFM with standalone JULES to be run with non-regular lat-lon grids +* New JULES-C configuration, the prototype configuration for UKESM1 +* Sea-ice changes for GC3.0 (Global Coupled configuration, version 3.0) + + +Technical changes +----------------- + +* Revamp of compilation procedure (see :doc:`/building-and-running/intro`) + + * Changes to the environment variables used to specify a build + * Option to extract and mirror on local machine, preprocess and build on a remote machine (e.g. Met Office Cray XC40) + * Addition of "platform configurations", to reduce the number of environment variable definitions required to build on a known platform + +* Ancillary data (e.g. fractional coverage, soil data) is now saved to the dump file + + * Each namelist in :doc:`/namelists/ancillaries.nml` gets a new flag, ``read_from_dump``, e.g. :nml:mem:`JULES_SOIL_PROPS::read_from_dump ` + * A dump file can now be used initialise an entire run, including ancillaries (except for river routing, for technical reasons) + +* Many additional ``rose-stem`` tests +* Replace testing for ice using ``sm_sat`` with logical arrays for soil and ice points +* Restructuring of ``rose-stem`` tests to allow for site configurations with more divergence between sites + + * As a result, JULES is now routinely tested on 3 platforms - Intel and gfortran compilers on Linux and CCE on the Cray + +* Remove the hijacking of the ice tile as a second urban tile when using two-tile urban schemes in the UM +* Replacement of old include files with modules + + +Bugs fixed +---------- + +* Fixed a long-standing off-by-one error in the instantaneous interpolation code (mode ``i`` - see :doc:`/input/temporal-interpolation`) +* Several small fixes to soil carbon and vegetation code +* Fix in river routing for bit-comparison with different processor decompositions in the UM +* Fix for IMOGEN in parallel mode +* Fix initialisation of some diagnostics diff --git a/doc/source/release_notes/JULES4-4.rst b/doc/source/release_notes/JULES4-4.rst new file mode 100644 index 00000000..a6c2da16 --- /dev/null +++ b/doc/source/release_notes/JULES4-4.rst @@ -0,0 +1,43 @@ +JULES version 4.4 Release Notes +=============================== + + +The JULES vn4.4 release consists of 31 tickets from 17 authors across 35 commits. Two further tickets were removed from the release due to issues. + +Full details of the tickets committed for JULES vn4.4 can be found on the `JULES shared repository Trac system `_. + +Science changes +--------------- + + * Add an option to set tile elevations to have absolute values above sea-level - see :nml:mem:`JULES_SURF_HGT::l_elev_absolute_height` + * Adjustment to downward longwave radiation for elevated tiles - see :nml:mem:`JULES_SURFACE::l_elev_lw_down` + * Nitrogen cycling - improved process representation for UKESM + * Use bare soil momentum roughness length, if supplied as an ancillary field + * Irrigation water taken first from deep soil layer then the river (code from the JULES Impact Model) + * Improvements to rivers_type='trip','rfm': storage in dump and partial parallelisation + * Alternative forms for methane emissions from wetlands, using different substrates + * Allow landuse with variable number of PFTs + * BVOC emissions allowed with trait physiology + * Change multi-layer snow indices of first layer + +Technical changes +----------------- + + * JULES fcm-make configs updated to be incompatible with FCM 2015.07.0 and later + * Rose-stem support for alternative Rose, Cylc and FCM versions + * Addition of OpenMP directives to some JULES code. + * Code coverage metrics for rose-stem suite + * Preparation for JULES memory duplication + * Removed snow_grnd_gb from closures benchmark test + + +Bugs fixed +---------- + + * Remove factor of 0.5 from snow albedo temperature dependence + * Fix a bug in the Nitrogen scheme for the implicit update of soil respiration when the soil C pool is exhausted. + * Fix drift in vegetation fractions + * Scaling bug in Taux + * Bug fix for irrig_water diagnostic - between crop seasons this is now zero + * Met Office VM: fix for update-jules-scripts file for JULES 4.3 + * JULES namelist broadcasts are out of sync diff --git a/doc/source/release_notes/JULES4-5.rst b/doc/source/release_notes/JULES4-5.rst new file mode 100644 index 00000000..dee993e1 --- /dev/null +++ b/doc/source/release_notes/JULES4-5.rst @@ -0,0 +1,48 @@ +JULES version 4.5 Release Notes +=============================== + + +The JULES vn4.5 release consists of 31 tickets from 19 authors across 35 commits. + +Full details of the tickets committed for JULES vn4.5 can be found on the `JULES shared repository Trac system `_. + +Science changes +--------------- + + * UKCA dry deposition working with 13 surface tiles + * Check litter flux carbon balance + * Allow litter carbon fluxes from variable numbers of PFTs + * Improved seasonal cycle of soil respiration: switch l_soil_resp_lev2 alters how soil temperature and moisture are used for respiration calculation. + * Added parameters to trait physiology for nitrogen in wood and roots - see :nml:mem:`JULES_PFTPARM::nr_io`, :nml:mem:`JULES_PFTPARM::nsw_io` and :nml:mem:`JULES_PFTPARM::hw_sw_io`. + * INFERNO model of fire emissions and burnt area - see :nml:mem:`JULES_VEGETATION::l_inferno` + * Option to represent crops using triffid - see :nml:mem:`JULES_VEGETATION::l_trif_crop` + * Remove MORUSES hard-wired roof coupling + * Add diagnostic for canopy FAPAR (Fraction of Absorbed Photosynthetically Active Radiation). + * JULES-CN: enabled nitrogen limitation of NPP - see :nml:mem:`JULES_VEGETATION::l_nitrogen` + * Added the FLake lake model into JULES (for UM use) + +Technical changes +----------------- + + * Variable renaming to support soil tiling + * Add JASMIN as a supported system for rose-stem jobs + * Fix Cray compiler warnings + * Protect print statements from the TRIP river routing code with PrintStatus + +Bugs fixed +---------- + + * Fix ozone diagnostics in JULES + +Documentation updates +--------------------- +Coding standards, and documentation can be viewed on the 'github page _'. + + * Update to coding standards to reflect and protect variable name changes + * Represent crops using TRIFFID + * JULES-CN + * Nitrogen trait physiology + * Check litter C flux carbon balance + * kgC and kgN in netCDF units metadata + * adding nfita to hydrology namelist + * add FAPAR diagnostic diff --git a/doc/source/release_notes/JULES4-6.rst b/doc/source/release_notes/JULES4-6.rst new file mode 100644 index 00000000..b42bac28 --- /dev/null +++ b/doc/source/release_notes/JULES4-6.rst @@ -0,0 +1,57 @@ +JULES version 4.6 Release Notes +=============================== + + +The JULES vn4.6 release consists of 43 tickets from 22 authors across 52 commits. + +Full details of the tickets committed for JULES vn4.6 can be found on the `JULES shared repository Trac system `_. + +Science changes +--------------- + + * Multiple ice tiles in a gridbox to simulate snowpacks at different elevations - see :nml:mem:`JULES_SURFACE::l_elev_land_ice` + * Modifications to snowpack physics to better represent deep, compact firn/snow on ice sheets - description at :nml:mem:`JULES_SURFACE::l_elev_land_ice` + * Option to link whole-plant maintenance respiration to soil moisture stress - see :nml:mem:`JULES_VEGETATION::l_scale_resp_pm` + * Read clay content of soil for soil carbon decomposition model from ancillary file - see :nml:lst:`JULES_SOIL_PROPS` + * Improved climate downscaling physics for ice elevation tiles + * Calculate FAO Penman-Monteith evapotranspiration for reference crop - see diagnostic fao_et0 + * Diagnostic form drag for sea ice (UM only) + * Calculation of new sea ice variables required for CMIP6 + * Implement a canopy clumping factor - see :nml:mem:`JULES_PFTPARM::can_struct_a_io` + * Allow for non-istropic scattering in plant canopies - see :nml:mem:`JULES_RADIATION::l_niso_direct` + * Increased flexibility to represent soil moisture stress on vegetation - see :nml:mem:`JULES_PFTPARM::fsmc_mod_io` and :nml:mem:`JULES_PFTPARM::fsmc_p0_io` + * Improved parameterisation of crop leaf senescence + * New crop harvest diagnostics + * Lake model FLake beneath multi-layer snow (UM only) + +Technical changes +----------------- + + * JULES-C-1p1 Regression Tests + * Remove the UM_FLAKE CPP macro + * Move sorp and n_inorg_turnover to namelist to enable user input. + * VM rose stem bug fixed. + * Add support for rose-stem on MONSooN + * Move some of the hard-wired crop parameters to :nml:lst:`JULES_CROPPARM` + * Remove UM descent.h include file and put values into JULES module descent.F90 + * Fix race conditions and improve OpenMP DEFAULTs + * Modularise and header refactor science/snow + +Bugs fixed +---------- + + * Fixed GC3 tstar_sice bug + * Corrected canopy nitrogen profiles - see :nml:mem:`JULES_VEGETATION::l_leaf_n_resp_fix`. This increases plant maintenance respiration. + * Reduced stem respiration with trait-based physiology + * Reinstated missing veg parms, for trait initialisation. + * Soil respiration bug resolved + * Corrected mistake in merging of crop PFT changes + * Fixed N diagnostic to avoid runtime crashes + * Fixed calculation of dust deposition exchange coefficient + * Fixed wetland emission of methane with TRIFFID on + * Fixed aerodynamic resistance diagnostic (UM diagnostic) + +Documentation updates +--------------------- +Coding standards, and documentation can be viewed on the 'github page _'. + diff --git a/doc/source/release_notes/JULES4-7.rst b/doc/source/release_notes/JULES4-7.rst new file mode 100644 index 00000000..6dc64953 --- /dev/null +++ b/doc/source/release_notes/JULES4-7.rst @@ -0,0 +1,97 @@ +JULES version 4.7 Release Notes +=============================== + + +The JULES vn4.7 release consists of 47 tickets from 19 authors. + +Full details of the tickets committed for JULES vn4.7 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #265. + +Science changes +--------------- + + * Enable soil tiling by the extraction of key calculations. These include: Infiltration rate and Soil moisture availability factor (beta). (#265) + + * Modifications to the rate of growth of snow grains - it uses the ET scheme of Taillandier (2007), JGR, 112, F03003 for the rate of growth and to relayer the grain size using its inverse as this is more consistent with conservation of SSA reported by Gallet et al. (2011). (#298) + + * JULES-CN: Soil_CN ratio changed from hard-wired to the namelist in prep for a PPE of JULES and JULES-CN the bio and hum N pools change from being prognostic to diagnostic via the soil bgc at the start of this routine and during initialisation. (#309, 288) + + * Add new irr_crop option: irr_crop = 0: continuous irrigation (i.e. the effectively the crop season is defined to last all year). It does not depend on crop characteristics (unlike irr_crop=2, which uses the crop model, or irr_crop=1, which estimates a typical crop season for that gridbox). (#312) + + * Diagnostics for individual components of snowpack mass balance, as specified by ISMIP6. (#314) + + * Diagnostics for components of surface radiation on land tiles. Requested by ISMIP6 for driving standalone icesheet models. (#315) + + * User initialised river storage. When dump_file=T, and use_file=T for rivers_sto_rp, then rivers_sto_rp needs to be in the dumpfile. When use_file=F for rivers_sto_rp, then rivers_sto_rp can be set to a constant value in this namelist. When dump_file=F, the rivers_sto_rp is initialised to zero. (extra log message to say that rivers_sto_rp is initialised to zero in this case). Therefore a dump file from a run without l_rivers=T and rivers_type='trip' can now be used to initialise a run with l_rivers=T and rivers_type='trip'. (#316 and #329 doc) + + * For fsmc_mod = 1, change the water extraction pattern so that it is proportional to plant available water rather than total water in the soil layers. Note: fsmc_mod=1 is not the recommended value in the JULES manual and it is not currently use in any of the documented configurations. This part of the code is also going through a detailed review as part of the soil moisture stress on vegetation group, which includes documenting the current status. (#320) + + * Add a new cpft-dependent input variable initial_c_dvi_io to specify when the crop should be initialised. (#324, 356 doc) + + * Allow perturbations to driving data, by specify an amount to be added to driving temperatures and/or an amount to multiply the driving precip variables by. This is achieved by adding a switch (l_perturb_driving) and two input variables (temperature_abs_perturbation and precip_rel_perturbation) to the JULES_DRIVE namelist. When l_perturb_driving is set to true, an amount (positive or negative) can be added to the driving temperature (temperature_abs_perturbation) and the precipitation variables can be multiplied by a factor (precip_rel_perturbation). (#326) + + * Fluxes JULES rose stem tests added: Some new GSWP2 tests for forecast configurations, New diagnostics to many existing tests, Switches on profiles that were written but disabled in carbon cycle tests, Tweaks to how we run on SPICE. (#330) + + * Change the defaults for the npft=9, ncpft=4 case in the rose upgrade macro vn44_t136 so that first 5 pfts are the same as the npft=5 case and the C3/C4 crop tiles have the same values as the C3/C4 grasses. (#336) + + * Allow sthuf (soil moisture) to be prescribed. (#348) + + * Soil refactor, following on from adding module statements etc to radiation and snow, this works on src/science/soil to add MOUDLE statements and INTENTS. (#351) + + * Update to metadata for jules_rivers_props so when grid_is_1d is false the following values in jules_rivers_props; nx_grid, ny_grid, reg_lat1, reg_lon1, reg_dlat, reg_dlon are required when running in parallel. Added a log message warning that the values are not used if grid_is_1d is false and the run is in parallel. (#293) + + * Add the soil tile dimension to JULES as a hard-coded singleton. (#305) + + * Fixed a bug in TRIFFID which causes loss of bit comparison that occurred when L_TRIF_CROP and L_NITROGEN were both TRUE: the soil nitrogen prognostics (stash 442, 443, 446) became dependent on the PE configuration. (#372) + + * Modularise and header refactor science/radiation Adds module and intents to the radiation code Removed implicit RESHAPES of some variables through subroutine calls and therefore removes nearly all the complicated dimensionalities in this area (ij, pfield, land_pts), making the code simpler. (#253) + + * Add vertically discretised soil C and N to TRIFFID. Adds a dimension to existing prognostics and discretizing existing code. The scheme is extended to link rooting profiles to availability and uptake of N requiring additional prognostics. (#288) + + +General/Technical changes +------------------------- + + * Improve coding standard docs. + * Move from includes to use modules for ccarbon.h Retire l_endgame as we only use endgame in the UM. + * Fix warnings in the fcm make log. + * OpenMP improvements. + * Add valgrind profiling as execution option in the Rose GUI. + + * Extra documentation on; namelist order, Update to release notes. + + * Nightly rose stem test added to the MO system to test the head of the trunk nightly. + + * Replace all ENDIF, ENDDO, IF(, MAX(, MIN(, EXP( and GAMMA/gamma to r_gamma with the working practices syntax. + + * Use "rose config dump" on the whole repository to tidy up the rose (Python) files. + * Update cylc5 syntax to cylc6 (Python). + * Improve the create_rose app script. It now takes 5 arguments, vn_from, vn_to, namelist_path, suite_name and jules_dir. + + + +Bugs fixed +---------- + + * Fixed the variable in the metstats_timesteps subroutine that was being incorrectly set for first and last second of day, which lead to gaps in the fire indices along some lines of longitude. (#323) + + * Fixed errors in UM GA7 AMIP code to run rose stem app with "rigorous" optimisation settings on SPICE. In particular: Formatted internal writes with incorrect format statements; ALLOCATEd variables not being DEALLOCATEd. (#328) + + * Fixed example put namelists. Updated parameters can_struct_a_io, fsmc_mod_io, and fsmc_p0_io in all example directories, and added missing parameters in the loobos_point_9pfts directory. (#354) + + * Clay frac bug, IF test for l_triffid=.false. added around clay_gb so that the test does not fail as clay_gb has not been populated as triffid is not run and therefore not clay_gb is not initialised and populated. (#307) + + * taux (wind stress) output inconsistency fixed by the initialisation of two variables in surf_couple_extra: cq_cm_u_1(:,:) = 0.0 and cq_cm_v_1(:,:) = 0.0 (#339) + + * Set z0_surft and lit_c_pft to zero in allocate_jules_arrays as they were not allocated and caused KGO failures. (#365) + + * Fixed calc_fsat so that values are not divded by small numbers. (#342) + + * Fixed the bug in multi-layer snow use of tile_map. It now checks to see if it is valid for the input dump configuration and converts from mapping tile IDs to pseudo levels. (#302) + + +Documentation updates +--------------------- +Coding standards, and documentation can be viewed on the 'github page _'. + diff --git a/doc/source/release_notes/JULES4-8.rst b/doc/source/release_notes/JULES4-8.rst new file mode 100644 index 00000000..96bfabd7 --- /dev/null +++ b/doc/source/release_notes/JULES4-8.rst @@ -0,0 +1,69 @@ +JULES version 4.8 Release Notes +=============================== + + +The JULES vn4.8 release consists of approximately 77 tickets from 26 authors, including work by many other people. + +Full details of the tickets committed for JULES vn4.8 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #400. + +Science changes +--------------- + + * Changes to calculate transpiration on tiles and as a gridbox mean. A resistance factor based on stomatal resistance excluding soil is calculated and then multiplied by evapotranspiration. This affects the diagnostics 'et_stom' and 'et_stom_gb'. (#400) + * Addition of interactive fire/vegetation, selected using :nml:mem:`JULES_VEGETATION::l_trif_fire`. Fire disturbance modifies vegetation dynamics and can be modelled by the INFERNO fire model or prescribed via an ancillary file. This is a preliminary version that will be developed further. (#456) + * Added option to allow downward longwave and net shortwave radiation to be used to force the model (see :ref:`list-of-jules-forcing-variables`). JULES now stops if too many or incorrect radiation variablse are provided (rather than carrying on if a valid combination was found). (#409) + * Added an option for the treatment of graupel in input to snow scheme (primarily for the UM; see :nml:mem:`JULES_SNOW::graupel_options`). (#414) + * Looping required for soil tiling functionality added in a disabled state (nsoilt still hard-coded to 1). (#379) + * Added the ability for hydrol_jls.F90 to work with tiled runoff once soil tiling is enabled in a later change. (#341) + + +General/Technical changes +------------------------- + + * Refactoring of albpft_jls.F90 to be more efficient. + * Improved code to calculate litter, landuse change and harvest fluxes. + * New namelist :nml:lst:`JULES_SOIL_BIOGEOCHEM`. The soil and vegetation components of TRIFFID have been separated. + * :nml:mem:`JULES_INITIAL::total_snow` defaults to .FALSE. + * :nml:mem:`JULES_OUTPUT::dump_period` controls the frequency with which dumps are written. + * River routining changes: user initialised surface and sub-surface storage and flows for RFM river routing. See :ref:`list-of-initial-condition-variables`. Two options for standalone river routing: 'rfm' or 'trip' in namelist :nml:lst:`JULES_RIVERS`. New remapping utilities provide efficient translation between land points and river points vectors. + * New and added diagnostics for UKESM, CMIP6 'NDVI_land'. See :ref:`output_variables_section`. + * Improved error checking and error messages. + * Print statement improvements. + * Urban namelists prefixed with 'jules'. + * Tidy up unused variables and an unused dummy argument in the FLake code. + * General code developments and improvements to meet the coding standards. + * A minor change to communication routines' API. + * OpenMP developments. + * Rationalisation of UM ancil routines, part 1 (#346) + * Removed redundant code from the soil ancillary reading code. (#450) + * Rose stem configurations for JASMIN, NIWA, CEH, Exeter Uni, remote JASMIN and MetO XCS computer. Ensure that the same tests are run at all sites. cylc7 compatable + * New or improved rose stem tests. + * Improvements to create-rose-app and suite_report.py + + + +Bugs fixed +---------- + + * Bug in the argument list to irrig_dmd, where the surface-tiled irrigated fraction was passed instead of the gridbox mean. (#389) + * Various fixes related to argument INTENTs (snow #396; soil respiration #392, h_blend_orog #452, surface flux code #412). + * Bug fixes for INFERNO fire model (soil carbon #415, incorrect rainfall #390, minor fixes #371). + * Bug fix in TRIFFID so soil nitrogen with l_trif_crop does not depend on processor configuration (#372) + * Bug fix for soil inorganic N in UM runs (#395) + * Bug fix in hydrology for when :nml:mem:`JULES_HYDROLOGY::l_wetland_unfrozen` = .TRUE. (#473) + * Initialisation of TRIFFID diagnostics (#313, #474, #479) + * Minor update to correct standalone river routing grid definition for non-regular grids (e.g. UKV variable resolution). (#410) + * Bug fix in the calculation of NPP in TRIFFID with N limitation. (#308) + * Fixed error in frequency of calls to phenology in long standalone runs. (#421) + * Bugs fixed so IMOGEN will restart more accurately from a dump. (#420) + * Bug fixes and improvements for layered soil CN model (#394, #407) + * Bug fix for albpft_jls.F90 (#458) + * Bug fix to allow compilation without netCDF (#464) + * Bug fixes for metadata and upgrade macro (#404, #459, #490) + +Documentation updates +--------------------- +Coding standards, and documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES4-9.rst b/doc/source/release_notes/JULES4-9.rst new file mode 100644 index 00000000..190b5145 --- /dev/null +++ b/doc/source/release_notes/JULES4-9.rst @@ -0,0 +1,65 @@ +JULES version 4.9 Release Notes +=============================== + + +The JULES vn4.9 release consists of approximately 60 tickets from 19 authors, including work by many other people. + +Full details of the tickets committed for JULES vn4.9 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #262. + +Science changes +--------------- + + * New parameter :nml:mem:`JULES_HYDROLOGY::s_pdm` represents the minimum soil wetness below which there is no saturation excess surface runoff from the PDM model. s_pdm can be made slope-dependent using :nml:mem:`JULES_HYDROLOGY::l_spdmvar`, with additional parameter :nml:mem:`JULES_HYDROLOGY::slope_pdm_max`. (#262) + * Extensions to the parameterisation of moisture stress on vegetation. There is now (a) the option of a stress function that is piece-wise linear in soil potential (:nml:mem:`JULES_VEGETATION::fsmc_shape` = 1) rather than soil volumetric moisture content (:nml:mem:`JULES_VEGETATION::fsmc_shape` = 0) and (b) the option of specifying pft-dependent soil potentials (:nml:mem:`JULES_VEGETATION::l_use_pft_psi`) at which the plant starts to experience water stress (:nml:mem:`JULES_PFTPARM::psi_open_io`) and where the plant is fully stressed (:nml:mem:`JULES_PFTPARM::psi_close_io`). (#541) + * Methane emissions can now be calculated from layered soil temperature (see :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_ch4_tlayered`). Methane flux can be removed from soil carbon stocks to close the carbon budget (see :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_ch4_interactive`). The choice of substrate used for methane production is now controlled using :nml:mem:`JULES_SOIL_BIOGEOCHEM::ch4_substrate` instead of l_wetland_ch4_npp. (#468) + * Updates to the INFERNO fire model (see :nml:mem:`JULES_VEGETATION::l_inferno`) including burning of the carbon in litter/soil pools. New diagnostics added including flammability (see :ref:`output_variables_section`). (#502) + * Extension to the scheme for calculating subgrid-scale snowpack properties and surface mass balance fields for icesheet coupling (see :nml:mem:`JULES_SURFACE::l_elev_land_ice`). Non-glaciated tiles (:nml:mem:`JULES_SURFACE_TYPES::elev_rock`) can now co-exist with the ice tiles (:nml:mem:`JULES_SURFACE_TYPES::elev_ice`) in the elevation classes, allowing for fractional ice extent in a gridbox. (#294) + * Allow soil moisture to be prescribed on a subset of soil levels (see :nml:mem:`JULES_PRESCRIBED_DATASET::prescribed_levels`). (#487) + * Improvements to the layered soil C and N model (see :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc`) which is now fully ready for use. (#454, #526) + * Layered C allowed with single-pool soil model. (#526) + * Preparatory work for the ECOSSE soil biogeochemical model. (#444, #518) + * New functionality to limit the drag over the sea at high wind speeds (only for coupled models). (#543) + +General/Technical changes +------------------------- + + * Further preparatory work for soil tiling, including i/o. + * Allocated arrays are given initial values and improved error messages from memory allocation. + * Further C fluxes and diagnostics made available to the UM. + * :nml:mem:`JULES_PFTPARM::fsmc_p0_io` added to UM namelists. + * Various UM-related improvements, including: single switch to allow runs with mixing ratio; avoiding hard-wired logical argument to swap_bounds; removed old logical related to "New dynamics"; removed the stash super array; removed unused array bounds. + * Wrapped non-LFRIC-compliant code using a preprocessor directive. + * General code developments and improvements to meet the coding standards. + * Added fcm make and rose stem configurations for building and testing JULES at NCI. + * Added Rose stem tests for TRIP rivers running with 2D data and RFM rivers. (#539, #567, #568) + * Add more information to trac.log by improving suite_report.py. + * rose-stem supported for MONSooN xcs-c. + * Various changes for Met Office, including nightly testing on xcs. + * New tutorial group for rose-stem. + * Change to suite-report.py for use with cylc 7. + * Updates to the app update script. + + +Bugs fixed +---------- + + * Corrected mismatches between certain subroutine interfaces and subroutine calls. (#471, #544) + * Fixed bug in reading of certain soil tile variables. (#498) + * Fixed bugs in TRIFFID litter fluxes. (#504) + * TRIFFID altered to do fewer calculations on points without veg or soil. (#509) + * Tidied up code issues between UM and JULES. (#522) + * Added interactive nitrogen to the loobos_jules_es_1p6 test and initialised more TRIFFID variables. (#512, #520) + * Bug fix for regridding between land and river routing grids for regular lat/lon river grids where the land model grid is defined as 1d land point only grids. (#524) + * Fixed uninitialised variables in surf_couple_extra_mod.F90. (#546) + * Bug fix in init_rivers_props.inc. (#539) + * Bug fix for crop ancillary variables in read_dump and write_dump. (#551) + * Corrected a bug in the sea ice albedo scheme, which affects the calculation of bare ice albedo when multilayer thermodynamics are used in coupled UM-JULES-NEMO-CICE. (#547) + * Bug fix to variable intent in surf_couple_implicit. (#542) + * Bug fix for UM runs relating to clash between STASH items (#557) + +Documentation updates +--------------------- +Coding standards, and documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES5-0.rst b/doc/source/release_notes/JULES5-0.rst new file mode 100644 index 00000000..b0af5d40 --- /dev/null +++ b/doc/source/release_notes/JULES5-0.rst @@ -0,0 +1,50 @@ +JULES version 5.0 Release Notes +=============================== + + +The JULES vn5.0 release consists of approximately 34 tickets from 12 authors, including work by many other people. + +Full details of the tickets committed for JULES vn5.0 can be found on the `JULES shared repository Trac system `_. + +This release was unusual in that it was closed to science tickets so as to allow work of a more technical nature, principally ensuring compliance with the coding standards and improved optimisation. + +The extensive styling changes that were introduced at vn5.0 have made minor changes to a large number of lines of code, meaning that updating your work from an older branch may not be as straightforward as with most release cycles. For advice on how best to upgrade your branch to vn5.0 see `Notes on moving to vn5.0 `_. + +Ticket numbers are indicated below, e.g. #230. + + +General/Technical changes +------------------------- + + * Applied a code style-checking script, also included as part of rose stem tests. (#230, 387, 593) + * Modularise the root_frac() subroutine to improve interface checking. (#571) + * More use of OpenMP threading to surface and soil code to improve performance. (#575, 600, 607) + * Various code changes to prevent or warn if an inconsistent combination of vegetation flags and parameters is used. When TRIFFID is on and the phenology model is off (not recommended), LAI is now set to the balanced LAI rather than taken from the (:nml:lst:`JULES_PFTPARM`) namelist. (#592) + * Remove references to outdated or deprecated functions (#577, 585), and other technical improvements. (#596, 616) + * More variables given initial values. (#579) + * Reduced size of outputs from rose stem tests. (#580) + * Superfluous messages from vegetation code removed. (#581) + * General code improvements to meet coding standards and use a consistent style. (#574, 576, 578, 584, 594, 620, 621) + * Namelists are printed before checking for errors, for easier debugging. (UM only, #582) + * Snowdepth diagnostic made available in the UM. (#569) + * Module leadership clarified across the code base. (#611) + * Unnecessary subversion properties removed. (#597) + + +Bugs fixed +---------- + + * Fixed minor bug in variable names when soil moisture prescribed. (#573) + * Prevent duplicate names for output streams. (#590) + * Fixed bug in vegetation competition routine lotka_eq. (#603) + * Fixed bug in output variable smc_avail_top. (#604) + * Fixed minor bugs in use of l_trait_phys. (#613) + * Corrected wood product pool diagnostics in the UM. (#587) + * Bugs fixed in soil respiration, and in carbon conservation diagnostics, for runs with N limitation. (#595) + * Enables ability to perform bit comparable NRUN in the UM. (#612) + * Fix JULES rose stem so that it works on the MO XCS-C system (aka MONSooN). (#615) + * Fixed broken hyperlinks in the user guide. (#636) + +Documentation updates +--------------------- +Documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES5-1.rst b/doc/source/release_notes/JULES5-1.rst new file mode 100644 index 00000000..ff665a4d --- /dev/null +++ b/doc/source/release_notes/JULES5-1.rst @@ -0,0 +1,62 @@ +JULES version 5.1 Release Notes +=============================== + + +The JULES vn5.1 release consists of approximately 40 tickets from 17 authors, including work by many other people. + +Full details of the tickets committed for JULES vn5.1 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #533. + +Science changes +--------------- + + * Addition of river overbank inundation module (for diagnostic calculation of overbank inundation fraction) - see l_riv_overbank in namelist :nml:lst:`JULES_RIVERS` and namelist :nml:lst:`JULES_OVERBANK`. (#679) + * Changes to the layered soil biogeochemistry model: (i) the mean soil temperature over the TRIFFID time step is now used to determine whether a layer is unfrozen (ii) mixing is considered when calculating the final respiration. (#663) + * Options for improved treatment of thin snow comprising the introduction of basal melting of thin snow layers on warm ground. See :nml:mem:`JULES_SNOW::i_basal_melting_opt`. (#533) + * Added capability to include latest harvest date to crop ancillary. See :ref:`list-of-spatially-varying-crop-properties`. (#653) + * Account for crop harvest and fire in the carbon conservation diagnostics. (#476) + * Carbon conservation diagnostic now only calculated on TRIFFID timesteps. (#643) + * Added the JULES-standalone version of improved saturation vapour pressure (qsat) calculations. (#635) + * Introduced basic slab ocean by allowing the model to update the sea surface temperature based on the energy balance, in the same way as it does for land and sea-ice. Also allows for a fixed sea surface albedo (see `fixed_sea_albedo`), rather than the parameterised options. (#642) + +General/Technical changes +------------------------- + + * Wetland CH\ :sub:`4` emission parameters have been added to :nml:lst:`JULES_SOIL_BIOGEOCHEM`. Parameters are :nml:mem:`JULES_SOIL_BIOGEOCHEM::t0_ch4`, :nml:mem:`JULES_SOIL_BIOGEOCHEM::const_ch4_cs`, :nml:mem:`JULES_SOIL_BIOGEOCHEM::const_ch4_npp`, :nml:mem:`JULES_SOIL_BIOGEOCHEM::const_ch4_resps`, :nml:mem:`JULES_SOIL_BIOGEOCHEM::q10_ch4_cs`, :nml:mem:`JULES_SOIL_BIOGEOCHEM::q10_ch4_npp`, and :nml:mem:`JULES_SOIL_BIOGEOCHEM::q10_ch4_resps`. (#483) + * i/o work to allow soil tiling to function correctly. (#684) + * Allow output of rate modifier diagnostics needed for offline spin up of soil carbon pools. (#589) + * Improvements to intermittent sampling for output. (#605) + * Removed repeated calculation of vegetation stocks of C and N from TRIFFID. (#618) + * Modularised JULES vegetation subroutines to enforce stricter interface checking. (#668) + * Replaced integer constants used with :nml:mem:`JULES_SOIL_BIOGEOCHEM::ch4_substrate` (the choice of substrate for wetland methane) with parameters. (#628) + * More time constants replaced by parameters. (#625) + * Namelist :nml:mem:`JULES_MODEL_ENVIRONMENT::lsm_id` added to allow the selection of the land surface model: JULES or CABLE. Note that the CABLE science routines have not been implemented yet. (#656) + * Redundant "include" files removed and rationalisation of other modules. (#689) + * Made the JULES source code (as close as possible to) compliant with the Fortran 2003 standard. (#699) + * Added OpenMP to the snow scheme to improve parallel performance. (#638) + * IMOGEN identified as a new science module, and other changes to list of module leaders. (#686, 666) + * Added basic MORUSES rose stem test (upgraded UKV science to PS39) and enhanced metadata. (#289) + * Added a new script to rose stem to ensure apps are consistent with rose metadata. (#645) + * Expanded the fcm-make metadata to make it easier to apply additional compiler flags to builds. (#632) + * Implemented a timeout for the JULES rose-stem in instances where an app/task "submit-fail" or stalls. (#672) + * Updated settings for JULES on Met Office XC40 (standalone suites should be updated where necessary to pick up the new settings) and Met Office linux testing to use ifort 16.0. (#630, 697). + +Bugs fixed +---------- + * Fixed bug in soil hydrology to prevent water erroneously coming out of the bottom of the soil. Use :nml:mem:`JULES_SOIL::l_holdwater` = T to allow water to be held on an impermeable layer. (#171) + * Bug fix affecting litterfall N flux when :nml:mem:`JULES_VEGETATION::l_landuse` = T. (#617) + * Bug-fix in the calculation of the albedo when :nml:mem:`JULES_RADIATION::l_embedded_snow` = T. (#533) + * Corrected a scalar/array mismatch in the arguments to the `plant_growth_n` subroutine. (#670) + * Fix to allow initialisation of CO\ :sub:`2` from a dump file. (#680) + * Minor fix for vegetation competition in runs with :nml:mem:`JULES_VEGETATION::l_ht_compete` = F and :nml:mem:`JULES_VEGETATION::l_trif_crop` = F. (#627) + * Corrected units for parameters `dfp_dcuo` and `eta_sl` in comments and documentation. (#646, 659) + * Minor correction to metadata for :nml:lst:`JULES_SOIL_PROPS` namelist. (#669) + * Fixed an allocation bug in the UM (#665). + * Bug in tiling that could affect lake quantities (in UM runs using FLake). (#641) + * Fix of a minor OpenMP race condition. (#674) + * Moved an ALLOCATE statement to fix a memory bug in the UM affecting ESM runs. (#639) + +Documentation updates +--------------------- +Documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES5-2.rst b/doc/source/release_notes/JULES5-2.rst new file mode 100644 index 00000000..6a1a5c71 --- /dev/null +++ b/doc/source/release_notes/JULES5-2.rst @@ -0,0 +1,75 @@ +JULES version 5.2 Release Notes +=============================== + + +The JULES vn5.2 release consists of approximately 52 tickets from 25 authors, including work by many other people. + +Full details of the tickets committed for JULES vn5.2 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #754. + +Science changes +--------------- + + * Introduced option for vegetation canopy drag with optional correction for the roughness sublayer - see :nml:mem:`JULES_VEGETATION::l_vegdrag_pft` and :nml:mem:`JULES_VEGETATION::l_rsl_scalar`. (#754) + * Soil decomposition added to the code for the ECOSSE soil model (which is not yet ready for use). (#570) + * Extension of the screen temperature decoupling diagnostics to screen humidity - only recommended for runs with the UM (atmospheric model). (#508) + * Added a new option to the sea albedo calculation to simulate the effect of freezing (sea-ice) below 271 K. (#770) + +General/Technical changes +------------------------- + + * Enabled support for new routines to calculate qsat (the saturated water mixing ratio) which are now the default for standalone JULES. (#685) + * Improved interface checking in the surface, fire, FLake and river routing routines. (#678, 728, 729) + * The clay ancillary variable can now have multiple layers (note these are the soil biogeochemistry layers, not soil moisture layers). Users should note that an existing run with :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = T that tries to read a single-layered clay variable from a file with :nml:mem:`JULES_SOIL_PROPS::const_z` = F will no longer work; a multi-layered clay field must be provided in this case. All other configurations can be updated. (#687) + * Added further IMPLICIT NONE statements and fixed subroutine interface issues. (#737) + * Minor modifications to IMOGEN (#430). + * Removed the l_flux_bc switch from the UM-coupling argument list and standalone code. (#775) + * Improved use of coupled model diagnostic code in standalone runs. (#740) + * Diagnostics from INFERNO (interactive fire model) made available to the UM. (#552) + * JULES parameters included in the Random Parameter (RP) scheme (for UM runs). (#675) + * Rationalised some of the code for the reading and writing of dumps. (#763) + * Alignment of JULES and UM urban control and initialisation code. (#319) + * Reduced model overhead when running DrHook profiling. (#782) + * Fixed oddities found while investigating the use of CamFort. (#769) + * JULES source code fully compliant with the Fortran 2003 standard. (#711) + * Corrections to code comments and other minor changes. (#725, 690) + * Clarified units of variables in the vegetation code. (#741) + * Enable the reading of PFT and soil parameters for CABLE runs via the JULES_PFTPARM_CABLE and JULES_NVEGPARM_CABLE namelists. (#694, 748) + * Minor edits to ensure future compatibility of .inc files with the umdp3_fixer used in Rose stem tests. (#762) + +Changes to testing +------------------ + + * Rose stem testing working on JASMIN. (#744) + * Improved the output of the umdp3 checker task in rose stem. (#764) + * Rose stem testing added for IMOGEN and GL7 and GL8 configurations. (#706, 648, 773) + * Added an OMP vs no-OMP Rose stem test for the ukv config to the MO XC40 and virtual machine platforms. (#732) + * Allowed the option of setting JULES_REMOTE and JULES_REMOTE_HOST when running on the Met Office Cray (meto-xc40-cce). (#755) + * Resolved oversubscription problems and rationalised the meto-linux rose stem. (#783) + +Bugs fixed +---------- + + * Fix to ensure TRIFFID competition does not try to access non-existent surface types. (#647) + * Fixed array/scalar mismatch in arguments to vegcarb. (#682) + * Corrected the dimensions given to the frac_prev array in `lotka_eq_jls.F90` (for runs with :nml:mem:`JULES_VEGETATION::l_trif_eq` = T and :nml:mem:`JULES_VEGETATION::l_ht_compete` = T). (#765) + * Fix to prevent floating point errors with CABLE. (#694) + * Use NINT to guard against imprecision in REAL/INTEGER conversion in routing code. (#726) + * Fixed bugs relating to windspeed-dependent unloading of snow from vegetation (UM only) and allowing soil rate modifier diagnostics in standalone runs. (#740) + * Correction related to indexing of snow fields in reconfiguration (UM only). (#676) + * Fixed certain snow diagnostics (UM stash fields 8,578 to 8,583). (#720) + * Correction to logic for canopy parameter updating (UM only). (#746) + * Example namelists updated for vn5.1. (#722) + * Fix of host specification in `runtime.rc` for site cehwl1. (#731) + * Updated the configuration for University of Exeter (`uoe-linux-gfortran.cfg`). (#735) + * Fix so rose stem IMOGEN tests work at NCI. (#792) + +Documentation updates +--------------------- + * Removed the science configurations section from the documentation. (#736). + * Updated the documentation (mainly release notes and hydrological terminology). (#738, 745) + * Updated documentation of fcm-make JULES_PLATFORM environment variable. (#739) + * Updated hyperlinks to Rose and FCM in the documentation. (#786) + +Documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES5-3.rst b/doc/source/release_notes/JULES5-3.rst new file mode 100644 index 00000000..e5af4753 --- /dev/null +++ b/doc/source/release_notes/JULES5-3.rst @@ -0,0 +1,58 @@ +JULES version 5.3 Release Notes +=============================== + + +The JULES vn5.3 release consists of approximately 27 tickets from 17 authors, including work by many other people. + +Full details of the tickets committed for JULES vn5.3 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #742. + +Science changes +--------------- + + * Improved initialisation of the surface exchange iteration (:nml:mem:`JULES_SURFACE::cor_mo_iter` = 4). (#742) + * Removed canopy radiation options (:nml:mem:`JULES_VEGETATION::can_rad_mod`) 2 and 3. (#791) + * Added nitrification, denitrification and leaching to the ECOSSE soil model (which is not yet ready for use). (#781) + * Allowed the use of a variable Charnock parameter, provided by a wave model via coupling, instead of a constant value, in runs of the UM (atmosphere-ocean model). See iseasurfalg = 4 or 5 in the jules_sea_seaice namelist. (#797) + +General/Technical changes +------------------------- + + * Coupling of river outflow from river grid to NEMO (ocean) grid via a 1D array. (#624) + * Added PBL gustiness parameter to namelist (:nml:mem:`JULES_SURFACE::beta_cnv_bl`). (#742) + * Changes required to run the INFERNO fire model interactively in the UM. (#800) + * Initial modifications to allow irrigation code to be used in the UM. (#809) + * Optimised aspects of the canopy drag scheme. (#795) + * Resolved issues identified by OpenMP-related compiler warnings. (#712) + * Improved OpenMP coverage. (#723, 815) + * Improved performance in UM global ensemble configuration. (#820) + * Removed unused code from the surface scheme in standalone JULES. (#753) + * Removed idfefs from some of the surf_couple routine argument lists. (#830) + * Introduced a framework to move to shared metadata between UM and standalone for ease of converting to and from UM and standalone apps, to assist with configuration management. This introduces the new namelist :nml:lst:`JULES_MODEL_ENVIRONMENT`. (#633) + * Ported to NIWA's XC50 platform. (#814) + * The meto-linux fcm-make configs have been converted to RHEL7. All Linux rose-stem tasks will run on RHEL7 SPICE nodes. Those using a meto-linux-intel-mpi build outside of rose-stem will need to set `ROSE_LAUNCHER_LIST = mpiexec.hydra` or make an equivalent change to their personal `rose.conf` file, and include the full path to the required MPI-enabled compiler. Refer to the `runtime-linux-intel.rc` file in rose-stem for details. (#835) + * Corrected bug in the make_jules_release script. (#796) + * Miscellaneous administrative changes. (#807, 839) + +Bugs fixed +---------- + + * Corrected a bug in the scalar roughness length diagnostic over sea when using anything other than a fixed roughness length, i.e. anything other than iseasurfalg=0. (#794) + * Fixed calls to mask compression routines in UM-only code. (#826) + +Changes to testing +------------------ + + * A test of the canopy drag scheme, loobos_vegdrag, based on loobos_gl8 has been added to rose-stem. (#795) + * Updated `umdp3_fixer.py` to run on \*.inc files, and included these in the rose stem test. (#776) + * Implemented code to align continuation ampersands in column 79 as part of `umdp3_fixer.py`. (#823) + * The Met Office rose stem suite now runs all Linux tasks on SPICE, and the metadata checker task is now included in the JASMIN rose stem suite. (#819) + * Correction for rose stem on MONSooN. (#852) + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#836) + +Documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES5-4.rst b/doc/source/release_notes/JULES5-4.rst new file mode 100644 index 00000000..c00f1efd --- /dev/null +++ b/doc/source/release_notes/JULES5-4.rst @@ -0,0 +1,61 @@ +JULES version 5.4 Release Notes +=============================== + + +The JULES vn5.4 release consists of approximately 29 tickets from 13 authors, including work by many other people. + +Full details of the tickets committed for JULES vn5.4 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #872. + +Science changes +--------------- + + * Improvements to fire-related vegetation mortality, including the addition of a PFT-specific fire mortality parameter :nml:mem:`JULES_PFTPARM::fire_mort_io` (previously mortality was taken directly from the burnt area as diagnosed by INFERNO and did not vary by PFT). (#872) + * Stomatal conductance can be modelled following the approach of `Medlyn et al. (2011) `_, via the switch :nml:mem:`JULES_VEGETATION::stomata_model`. A single-parameter version of the model is coded, requiring the PFT-specific parameter :nml:mem:`JULES_PFTPARM::g1_stomata_io`. (#766) + +General/Technical changes +------------------------- + + * The RFM river routing scheme is now available to the UM (atmospheric model), and both standalone and UM runs use the same code. See :nml:lst:`JULES_RIVERS`. (#876) + * The :nml:lst:`JULES_RIVERS` namelist now controls river hydrology in both standalone and UM-coupled modes. (The UM namelist 'run_rivers' has been removed.) (#867) + * The surface conductance (`gs`) is now part of the specification of the initial state (and included in dumps) only when it is required (i.e. only if :nml:mem:`JULES_VEGETATION::can_rad_mod` = 1; see :ref:`list-of-initial-condition-variables`). (#859) + * Use ``swap_bounds`` routine(s) from ``halo_exchange_mod`` module (not the old 2C subroutine) in UM runs. (#367) + * Extensive refactoring of ``surf_couple_extra``, including removal of ``ifdef`` in argument list. (#806, 833) + * Tidied/refactorised the photosynthesis code. (#817) + * Improved checking and reporting of the IMOGEN setup. (#850) + * Tidied the header of ``control.F90``, removing duplicate and unused variables. (#873) + * Access subroutines ``set_levels_list`` and ``set_pseudo_list`` using modules, removing the need for ``DEPENDS ON``. (#880) + * Improved performance of land surface routines in RA and GA configurations. (#861) + * Set up CABLE directory structure and initialise essential variables for `surf_couple_radiation`. (#799) + * Allowed variables used in the build process to have platform-specific defaults which can be overridden by the user. (#853) + * Met Office Cray users: Direct extract of code to the Cray is the default for meto-xc40-cce builds. Users are encouraged to remove fcm_make2 tasks and set ``JULES_REMOTE = local`` to take advantage of faster end-to-end compilations and reduce load on the HPC. Set ``JULES_REMOTE = remote`` to retain builds which require an fcm_make2 task. See :ref:`fcm-make-environment-variables`. (#854) + * Reviewed and simplified fcm-make metadata compulsory variables and made current apps validate. (#855) + * Improved selected metadata in the :nml:lst:`JULES_SOIL_BIOGEOCHEM` and :nml:lst:`JULES_SOIL_ECOSSE` namelists to prevent errors when using the Rose GUI. (#862) + + +Bugs fixed +---------- + + * Fixed the radiatively-coupled roof in MORUSES, using the temporary logical :nml:mem:`JULES_TEMP_FIXES::l_fix_moruses_roof_rad_coupling`, in the new namelist :nml:lst:`JULES_TEMP_FIXES`. The supposedly radiatively-coupled roof is in fact **uncoupled** without this bug fix. (#610) + * Corrected initialisation of frozen/unfrozen soil - no longer assumes constant soil properties with depth. (#749) + * Removed a bug in the snow scheme when :nml:mem:`JULES_SURFACE::l_point_data` = TRUE and :nml:mem:`JULES_VEGETATION::can_model` = 4: the snow covered fraction formulation is now only used for tiles that do not use the snow canopy option (see :nml:mem:`JULES_SNOW::cansnowpft`), rather than for all tiles. (#879) + * Prevent out-of-bounds operations in sf_exch. (#846) + * Ensure that `ntype` is set before use in UM model runs. (#878) + * Corrected the units of the ocean near-surface chlorophyll content (used in the calculation of the ocean surface albedo), using the temporary logical `l_fix_osa_chloro`. Only affects runs with the UM. (#874) + + +Changes to testing +------------------ + + * Rose-stem fcm-make tasks will ignore lock files that would otherwise prevent retriggering. (#860) + * Expanded coverage of the rose-stem metadata validation test to include more apps. (#886) + * Upgraded ``suite_report.py``. (#889) + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#881) + * Example namelists point_mead_2_crops have been updated to be consistent with the published JULES-crop runs in `Williams et al. (2017) `_. + +Documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES5-5.rst b/doc/source/release_notes/JULES5-5.rst new file mode 100644 index 00000000..bfa8a0e1 --- /dev/null +++ b/doc/source/release_notes/JULES5-5.rst @@ -0,0 +1,46 @@ +JULES version 5.5 Release Notes +=============================== + + +The JULES vn5.5 release consists of approximately 18 tickets from 14 authors, including work by many other people. + +Full details of the tickets committed for JULES vn5.5 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #434. + +Science changes +--------------- + + * Methane feedbacks from natural wetlands added to IMOGEN - see :nml:mem:`IMOGEN_RUN_LIST::land_feed_ch4`. This is done by adding an anomaly relative to the default emissions. Users should confirm that the wetland emissions are correct - see the notes under :nml:mem:`IMOGEN_RUN_LIST::land_feed_ch4`. + * Code changes for the GL9 configuration, including options to specify specific values for the roughness length of each Plant Functional Type (:nml:mem:`JULES_VEGETATION::l_spec_veg_z0`) and to impose a maximum-allowed value of the canopy heat capacity for vegetation (:nml:mem:`JULES_VEGETATION::l_limit_canhc`). (#903) + * Additional options for distributed form drag (`fd_stab_dep`) - not available in off-line JULES. (#870) + + +General/Technical changes +------------------------- + + * Separate the calculation of plant-soil N fluxes from the updating of the soil stores - to allow the fluxes to be used with alternative soil models. (#651) + * Initial steps towards representing dry deposition in JULES: new namelists :nml:lst:`JULES_DEPOSITION` and :nml:lst:`JULES_DEPOSITION_SPECIES`. Note that deposition cannot yet be modelled in JULES. (#662) + * River routing code tidied. (#877) + * The interface (API) between the JULES program and the CONTROL subroutine now includes the atmospheric forcing variables as input and the gridbox mean surface flxues as output. This creates a clean "managed API" that can be used by parent models to call the JULES code at the CONTROL subroutine level. (#914) + * Added diagnostics for absorbed photosynthetically active radiation (`apar` and `apar_gb`) and gridbox mean leaf area index (`lai_gb`) - see :ref:`output_variables_section`. (#614, 890) + * Corrected the units given for the ozone flux diagnostic (`flux_o3_stom`). (#905) + * Improved computational performance of ice-related and other routines. (#866, 894) + * Removed code only used for UM (atmospheric model) diagnostics; now using the sf_diag structure. (#899) + * Changes for UM diagnostics - to accommodate the fact that copydiag is now in a module. (#908) + * Moved the CABLE soil parameters to a separate namelist :nml:lst:`CABLE_SOILPARM`. (#900) + * Improvements to code involved in creating the JULES release, including the documentation. (#893) + + +Bugs fixed +---------- + + * Removed use of uninitialised memory in RFM river routing scheme. (#896) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#924) + +Documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES5-6.rst b/doc/source/release_notes/JULES5-6.rst new file mode 100644 index 00000000..ff0e8807 --- /dev/null +++ b/doc/source/release_notes/JULES5-6.rst @@ -0,0 +1,45 @@ +JULES version 5.6 Release Notes +=============================== + + +The JULES vn5.6 release consists of approximately 14 tickets from 11 authors, including work by many other people. + +Full details of the tickets committed for JULES vn5.6 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #864. + +Science changes +--------------- + + * Added the Farquhar model of photosynthesis for C\ :sub:`3` plants - see :nml:mem:`JULES_VEGETATION::photo_model`. (#864) + * Added the COARE algorithm for drag over sea, including functionality to reduce the drag at very high wind speeds - only affects runs with the UM. (#848) + + +General/Technical changes +------------------------- + + * UM and JULES metadata consolidated for namelists :nml:lst:`JULES_RADIATION` and :nml:lst:`JULES_VEGETATION`. (#822) + * Preparatory work towards including irrigation demand in the UM. (#811) + * Allowed the dimension names :nml:mem:`JULES_INPUT_GRID::sclayer_dim_name`, :nml:mem:`JULES_INPUT_GRID::tracer_dim_name`, :nml:mem:`JULES_INPUT_GRID::bl_level_dim_name` to be read from namelist :nml:lst:`JULES_INPUT_GRID`. (#937) + * Improved error handling in subroutines ``set_levels_list`` and ``set_pseudo_list``. (#935) + * Updated the UM STASH diagnostics routines to use a modularised version of copydiag. (#938) + * Added further OpenMP optimisations for GA8 model routines. (#941) + * Additions of ``#if defined(LFRIC)`` to allow coupling of ``surf_couple_extra`` to LFRic. (#943) + * Altered OMP directives to remove data race conditions. (#952) + * Removed the requirement to have some environment variables that are used in build configs defined/initiliased at the app/suite level. (#939) + + +Changes to testing +------------------ + * Updated rose stem testing to include JULES-ES-1.0 configuration. (#915) + * JULES can be built at the Bureau of Meteorology (Australia). (#930) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#950) + +Note that compilation of the User Guide now requires Sphinx 1.4 or higher. + +Documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES5-7.rst b/doc/source/release_notes/JULES5-7.rst new file mode 100644 index 00000000..4fdd432e --- /dev/null +++ b/doc/source/release_notes/JULES5-7.rst @@ -0,0 +1,62 @@ +JULES version 5.7 Release Notes +=============================== + + +The JULES vn5.7 release consists of approximately 34 tickets from 16 authors, including work by many other people. + +Full details of the tickets committed for JULES vn5.7 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #548. + +Science changes +--------------- + + * Soil tiling made available - see :nml:mem:`JULES_SOIL::l_tile_soil`. Each land gridbox can be modelled using a single soil column or with a separate soil column for each surface tile. (#548) + * Enabled the simulation of multiple crops in a growing season, and therefore crop rotations - see :nml:mem:`JULES_VEGETATION::l_croprotate`. (#821) + * Added thermal adaptation and acclimation of leaf-level photosynthesis - see :nml:mem:`JULES_VEGETATION::photo_acclim_model`. (#863) + * Remaining source/sink terms for inorganic nitrogen included with the ECOSSE soil model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 3). (#788) + + +General/Technical changes +------------------------- + + * New functionality added to allow for a new vegetation biogeochemical model. Introduced more extensive use of modules to control the read and write of variable states, and FORTRAN type objects to control data flows. This code is not yet suitable for general use. (#888) + * Technical work for the implementation of the Robust Ecosystem Demography (RED) dynamic vegetation model. (#902) + * Moved allocation statements into the modules that hold the variables (and out of the monolithic allocate_jules_arays.F90). (#978) + * Improved processing of the values read from namelist :nml:lst:`JULES_OVERBANK`. (#987) + * Added a KIND type to the declarations of REAL variables. (#958, 996, 997) + * Removed some redundant operations from the science code. (#1001) + * Removed redundant arguments for copydiag_3d (affects UM runs only). (#954) + * Added STASH code controls for a new scale-dependent gust diagnostic in the UM. (#984) + * Trivial change to USE statements relating to a UM change to atm_fields_mod. (#1003) + * Further work on CABLE front end, adding namelists :nml:lst:`CABLE_PROGS` and :nml:lst:`CABLE_SURFACE_TYPES`. (#940) + * Tidied to remove compiler warnings related to um_parvars (decomposition) and unused variables (NAG compiler), and to make JULES compliant with changes to UM debug compiler flags. (#963, 966, 1002) + * Added some missing platforms to the metadata for fcm-make (so those are available in rose edit). (#976) + * Fixed the make_jules_release script to push latest documentation onto the master on GitHub. (#957) + * The example namelists (difficult to maintain) and benchmarking suite (obselete) have been removed. (#928, 969) + + +Bugs fixed +---------- + + * Bug fixes for the RothC-based soil biogeochemistry model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2) with :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = TRUE and :nml:mem:`JULES_VEGETATION::l_nitrogen` = TRUE. (#681) + * Prevented race condition in leaf_mod. (#1009) + + +Changes to testing +------------------ + + * Added NAG compiler to Met Office linux test suite. (#955) + * Fixed JULES rose stem build jobs on the VM. (#956) + * Updated NIWA rose-stem configuration for Maui HPC. (#965) + * Changed the path to data and libraries for rose stem testing on JASMIN. The default is the new jules group-workspace, and an environment variable JASMIN_JULES_BASE_DIR can be exported and picked up by rose stem. (#967) + +Documentation updates +--------------------- + + * Improved description of :nml:mem:`JULES_RADIATION::l_embedded_snow`. (#916) + * Assorted clarifications in documentation and comments. (#980) + * Basic infrastructure provided to support future JULES Documentation Papers. (#968) + * Updates associated with many of the above changes, and release notes. (#995) + +Documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES5-8.rst b/doc/source/release_notes/JULES5-8.rst new file mode 100644 index 00000000..0714ab6b --- /dev/null +++ b/doc/source/release_notes/JULES5-8.rst @@ -0,0 +1,42 @@ +JULES version 5.8 Release Notes +=============================== + + +The JULES vn5.8 release consists of approximately 19 tickets from 9 authors, including work by many other people. This was an unusual release cycle as it was primarily aimed at technical developments in support of changes to the Unified Model system. + +Full details of the tickets committed for JULES vn5.8 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #919. + + +General/Technical changes +------------------------- + + * The surf_couple* routines have been restructured to separate land and sea/sea-ice parts - making the code clearer and facilitating the implementation of CABLE into the JULES framework. (#919) + * Fields passed by argument rather than via USE statements. (#1022, #1024, #1025, #1028, #1029, #1030, #1037, #1038, #1043) + * Added :nml:mem:`JULES_OUTPUT::dump_period_unit` to allow the units of :nml:mem:`JULES_OUTPUT::dump_period` to be years or seconds. (#1021) + * Removal of the old qsat routines. (#1015) + * Access the gather_field and scatter_field subroutines via modules. (#1051) + * The url fields in HEAD metadata now have the "latest" tag, allowing both the UM and JULES to have the same url field. (#1017) + + +Bugs fixed +---------- + + * Bug fix to allow runs with soil tiling that do not rely on broadcastng values. (#1048) + * Bug fix to prevent array bounds error with river routing, and other minor changes to river routing. (#1049) + * Fix to allow compilation with pgfortran as part of UM-JULES. (#1010) + + +Changes to testing +------------------ + + * Tidied some rose stem apps. (#1050) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#1040) + +Documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES5-9.rst b/doc/source/release_notes/JULES5-9.rst new file mode 100644 index 00000000..b02beb50 --- /dev/null +++ b/doc/source/release_notes/JULES5-9.rst @@ -0,0 +1,55 @@ +JULES version 5.9 Release Notes +=============================== + + +The JULES vn5.9 release consists of approximately 21 tickets from 11 authors, including work by many other people. + +Full details of the tickets committed for JULES vn5.9 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #499. + +Science changes +--------------- + + * The FLake lake model is now available in standalone JULES (as well as in the UM), modelling sub-surface conditions on the lake tile - see :nml:mem:`JULES_SURFACE::l_flake_model`. (#499) + * Fix to stop snow from accumulating on unfrozen lakes when running the FLake lake model. (#1057) + * Options to disaggregate the albedo of bare soil between the VIS and NIR regions and to include the zenith-angle dependence of the bare soil albedo have been included. See :nml:mem:`JULES_RADIATION::l_hapke_soil` and :nml:mem:`JULES_RADIATION::l_partition_albsoil`. (#1020) + + +General/Technical changes +------------------------- + + * Modifications to ensure the irrigation namelist for standalone JULES is consistent with the UM namelist structure. This involved moving irrigation switches to namelist :nml:lst:`JULES_IRRIG` and adding the :nml:lst:`JULES_IRRIG_PROPS` namelist for ancillary fields. (#838) + * Added initial control-level code for water resources. (#1018) + * The interface for the `river_control` subroutine now follows the model used by the `surf_couple_*` routines. This is part of activities to create a standalone river routing capability. (#1066) + * Added latent heat flux diagnostics separately for land and sea/sea-ice (Unified Model runs only). (#992) + * Surface diagnostics for 1.5m temperature, specific and relative humidity, dewpoint temperature, and fog fraction separately over ocean (sea + sea ice) and land made available in the UM (not available in standalone JULES). (#1074) + * Removed unused arguments, to avoid UM compiler warnings. (#1069) + * Optimisation of code used in GA9. (#1071) + * Added `ONLY`\ s to all `USE` statements that did not have them, to avoid undesirable effects. (#1072) + * All transparent, non-functional metadata consolidated with the UM, including `sort-key`, `description`, `url` and `help`, which has been removed where duplicated by the JULES user guide or merged in. (#1055) + * Keep standalone and UM JULES meta data consistent. (#1083) + + +Bugs fixed +---------- + + * Fixed bug that affected the reading of soil ancillary fields when :nml:mem:`JULES_SOIL_PROPS::const_z` = TRUE in the JULES_SOIL_PROPS namelist. The bug had the potential to result in some soil ancillary fields being zero - which would likely have resulted in an obviously wrong result and/or a model crash. (#1080) + * Fixed bug in the reading of dumps containing rain_seed fields. (#1059) + * Fixes for various issues related to argument intents. (#1058, 1062) + * Fix for UM configs with iseasurfalg=2 (m10 now initialised). (#975) + + +Changes to testing +------------------ + + * The gswp2_irrig_limit rose stem tests are included in the set run at UKCEH. (#1053) + * Added a further rose stem test with irrigation. (#838) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#1078) + +Documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES6-0.rst b/doc/source/release_notes/JULES6-0.rst new file mode 100644 index 00000000..b9470ba3 --- /dev/null +++ b/doc/source/release_notes/JULES6-0.rst @@ -0,0 +1,48 @@ +JULES version 6.0 Release Notes +=============================== + + +The JULES vn6.0 release consists of approximately 18 tickets from 10 authors, including work by many other people. + +Full details of the tickets committed for JULES vn6.0 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #847. + +Science changes +--------------- + + * Added a microbial scheme for methane production (see :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_ch4_microbe`). (#847) + * Changes to soil evaporation: added a PFT-specific factor to multiply soil conductance under the canopy (:nml:mem:`JULES_PFTPARM::gsoil_f_io`) and a switch to limit soil conductance above the critical point (:nml:mem:`JULES_HYDROLOGY::l_limit_gsoil`). (#1093) + * Added option (l_icerough_prognostic) to use the prognostic sea ice roughness length calculated in CICE, rather than a constant value (available only when coupled). (#583) + * Calculate sea ice penetrating solar radiation to be sent to sea ice model. (#1100) + + +General/Technical changes +------------------------- + + * Irrigation code adapted for use with :nml:mem:`JULES_WATER_RESOURCES::l_water_resources` = TRUE. (#1086) + * Surface type IDs have been made available to JULES on a switch ``l_surface_type_ids``, however they currently have no functionality and are not passed to the JULES I/O. As part of the metadata consolidation project the namelists :nml:lst:`JULES_SURFACE_TYPES` and `JULES_LSM_SWITCH` are now consolidated, the latter by amalgamating it with :nml:lst:`JULES_MODEL_ENVIRONMENT`. The GUI panels are also now consistently named in UM and standalone. In parallel runs, informative output can now also be limited to Task 0 (see :nml:lst:`JULES_PRNT_CONTROL`). (#1095) + * Prevented duplicate (lat,lon) pairs being prescribed. (#1107) + * Extended the TYPE design to sweep up several small modules. (#1102) + * Optimisation in snow control routine. (#1110) + * Removed some default values for values read via the :nml:lst:`JULES_DRIVE` namelist, and improved triggering. (#1033) + * Initialised further namelist variables before use. (#598) + * Fixed bad characters in metadata. (#1103) + * Further work to keep JULES and UM metadata consistent. (#1118) + + +Bugs fixed +---------- + + * Added option (:nml:mem:`JULES_TEMP_FIXES::l_accurate_rho`) to use accurate calculation of surface air density in surface exchange calculations. (#194) + * Fix to remove erroneously large river flows at river mouths with RFM (:nml:mem:`JULES_RIVERS::i_river_vn` = 2). (#1081) + * Fixed unallocated TRIFFID variable in the new progs structure. (#1109) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#1097, 1112) + +Documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES6-1.rst b/doc/source/release_notes/JULES6-1.rst new file mode 100644 index 00000000..a78728ae --- /dev/null +++ b/doc/source/release_notes/JULES6-1.rst @@ -0,0 +1,51 @@ +JULES version 6.1 Release Notes +=============================== + + +The JULES vn6.1 release consists of approximately 21 tickets from 13 authors, including work by many other people. + +Full details of the tickets committed for JULES vn6.1 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #949. + + +General/Technical changes +------------------------- + + * Added the technical infrastructure to activate irrigation in the UM (atmosphere model). (#949) + * Irrigation timestep is controlled by :nml:mem:`JULES_IRRIG::nstep_irrig`. (#1146) + * Minor restructuring of water resources code. (#1122) + * The handling of the MORUSES roughness length in the surface exchange has been made more robust and the functionality for calculating urban morphology from the empirical relationships of Bohnenstengel et al. 2011 has also been fixed. (#1106) + * Forcing and lake variables bundled into TYPEs. (#1136, 1135) + * Conversion of initialisation and io/dump include files to modules, including some reorganisation required for River.Exe (standalone rivers-only executable). (#1158) + * CABLE lai_pft and canht_pft initialised from new namelist :nml:lst:`CABLE_PFTPARM`. (#1119) + * Miscellaneous small corrections to code and documentation. (#1143) + * Added new 1.5m visibility diagnostics to sfdiags (only for UM). (#1134) + * Improved performance in RA3 configurations. (#1113) + * Added further platform files for JASMIN. (#1145) + + +Bugs fixed +---------- + + * Corrected previously uninitialised PFT parameters when coupled to the UM. (#1137) + * Minor bug fixes and metadata updates for IMOGEN. (#1126) + * Bug fixes for seed_rain. (#1129, 1166) + * Prevent memory issues when using the INFERNO fire scheme in UM configurations. (#1149) + * Bug fix to add Rose metadata and upgrade macro for :nml:lst:`JULES_VEGETATION_PROPS` namelist. (#1141) + + +Changes to testing +------------------ + + * Reflected changes in the JASMIN environment (parallel netcdf and SLURM scheduler) in the settings for rose stem. (#1120) + + +Documentation updates +--------------------- + + * Revised presentation of the available diagnostics. (#1139) + * Updates associated with many of the above changes, and release notes. (#1157) + +Documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES6-2.rst b/doc/source/release_notes/JULES6-2.rst new file mode 100644 index 00000000..47b54e48 --- /dev/null +++ b/doc/source/release_notes/JULES6-2.rst @@ -0,0 +1,50 @@ +JULES version 6.2 Release Notes +=============================== + + +The JULES vn6.2 release consists of approximately 23 tickets from 15 authors, including work by many other people. + +Full details of the tickets committed for JULES vn6.2 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #470. + + +Science changes +--------------- + + * Added the ability to label and trace a subset of the soil carbon in the RothC layered model - see :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_label_frac_cs`. (#470) + * Replaced original logical for corrections to coastal tiling with a 3 way switch (:nml:mem:`JULES_TEMP_FIXES::ctile_orog_fix`). The latest improved fix combines the previous fix over sea with the original behaviour over land. (This is mainly relevant for runs with the Unified Model.) (#1184) + +General/Technical changes +------------------------- + + * Improvements and bug fixes for river grid and flow directions. (#1170) + * Selected output variables are now available on the river grid. (#1163) + * Technical work coupling the RED vegetation model to JULES. This is early in a staged process and RED is not yet available for general use. (#1034) + * Only check for duplicate lat-lon coordinates if those are set using constant values. (#1164) + * Variables related to fluxes and atmospheric chemistry bundled into TYPEs. (#1104, 1159) + * Removed momentum calculations for LFRic as those are now done in bespoke LFRic code. (#1144) + * Further work towards enabling interoperability between the JULES and CABLE land surface models - this step dealing with CABLE prognostic variables (see :nml:lst:`CABLE_PROGS`). (#1131) + * Removed most compiler warnings flagged by UM builds. (#1187) + * Ported the JULES codebase to the Met Office's EX1A system. (#1193) + * Updated Python scripts to be Python 3 compatible. (#1091) + * Preparing the JULES vn6.2 release. (#1204) + + +Bugs fixed +---------- + + * Bug fix to correct an array addressing issue in snow albedo calculations with :nml:mem:`JULES_RADIATION::l_embedded_snow` = TRUE. (#1064) + * Deallocating a few more arrays in ancil_info. (#1190) + * Fix to ensure that in coupled NWP models lake ice temperatures (where lakes are defined as sea points) evolve correctly - this is fixed by setting :nml:mem:`JULES_TEMP_FIXES::l_fix_lake_ice_temperatures` = TRUE. (#1161) + * Prevent error in internal write of ctile_orog_fix (potentially many characters long) into a 3 character buffer. (#1205) + * Fix arguments to subroutine next_time. (#1209) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#1156, 1186, 1192, 1198) + +Documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES6-3.rst b/doc/source/release_notes/JULES6-3.rst new file mode 100644 index 00000000..b0f2b648 --- /dev/null +++ b/doc/source/release_notes/JULES6-3.rst @@ -0,0 +1,60 @@ +JULES version 6.3 Release Notes +=============================== + + +The JULES vn6.3 release consists of approximately 28 tickets from 14 authors, including work by many other people. + +Full details of the tickets committed for JULES vn6.3 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #1142. + + +Science changes +--------------- + + * Restructured the parameterisation of thermal acclimation of photosynthesis to permit a wider range of configurations - see :nml:mem:`JULES_VEGETATION::photo_acclim_model`. (#1142) + * Updated soil N limitation in layered CN model (only applies when :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = TRUE). (#1213) + + +General/Technical changes +------------------------- + + * Improved nitrogen leaching for vertically-resolved soil biogeochemistry. (#1219) + * Allowed the use of daily files for input and output (via time templating for input files). (#1215) + * Further developments towards the RED vegetation model. (#1182) + * Refactored IMOGEN in preparation for adding netcdf reading and variable resolution. (#1214) + * Added functionality for the first phase of a standalone Rivers executable. This uses JULES I/O and is still under development; it currently is not scientifically correct as a result of a timestamp issue and does not include dumping capability. (#1084) + * Namelists `jules_urban2t_param` and `jules_urban_switches` amalgamated into :nml:lst:`JULES_URBAN`, which is also now consistent with the module name. (#1077) + * Updated metadata for bedrock and layered soil carbon. (#1234) + * Framework for a shared metadata solution introduced initially with namelist items from `jules_surface` and `jules_vegetation` currently shared with LFRic. (#1195) + More information on sharing JULES metadata can be found here: `SharingJULESmetadata `_ + * Minor adjustment to how FLake variables are dealt with during initialisation. (#1169) + * Modularised and refactored subroutine vgrav. (#1199) + * Rivers variables bundled in a new TYPE. (#1176) + * Modularised further UM-only files. (#1221) + * Removed the soil carbon variable cs from the UM, in prepration for the introduction of layered soil carbon. (#1210) + * Removed snowmelt_ij from fluxes_mod. (#1167) + * Tidied code to remove compiler warnings. (#1245) + * Revised the implementation of defining the veg/soil parameters to be passed to CABLE as a single TYPE, following them being read in through namelists. We also implement a working variables TYPE to hold variables at the top-level so that they may be passed between pathways (i.e explicit, implicit); as well as between time steps (at least until they are elevated to prognostics level). (#1223) + * Added a further restriction on the type of processor used for rose stem testing on JASMIN. (#1222) + * Updated list of module leaders. (#1240) + + +Bugs fixed +---------- + + * Fixes to FLake surface exchange and decoupling FLake from the soil column. (#1094) + * Added missing metadata for PFT parameter `dust_veg` (only used in the UM). (#1206) + * Corrected the definitions of the surface longwave radiation diagnostics. (#1220) + * Fixed a bug that prevented files from being closed when running with MPI. (#1241) + * Ensured that soileccose types are set up correctly. (#1229) + * Ensured Python3 is in path on both MONSooN and JASMIN systems. (#1216, 1231) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#1243) + +Documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES7-0.rst b/doc/source/release_notes/JULES7-0.rst new file mode 100644 index 00000000..be5695e1 --- /dev/null +++ b/doc/source/release_notes/JULES7-0.rst @@ -0,0 +1,64 @@ +JULES version 7.0 Release Notes +=============================== + +The JULES vn7.0 release consists of approximately 31 tickets from 20 authors, including work by many other people. + +Full details of the tickets committed for JULES vn7.0 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #911. + + +Science changes +--------------- + + * New functionality for modelling bioenergy crops - see :nml:mem:`JULES_VEGETATION::l_trif_biocrop` and :nml:mem:`JULES_VEGETATION::l_ag_expand`. (#911) + * Implemented a socio-economic factor in the fire ignition and suppression parameterisation in INFERNO, based on a Human Development Index (HDI). (#1284) + * A new logical switch :nml:mem:`JULES_SURFACE::l_mo_buoyancy_calc` enables an interactive buoyancy in the calculation of the surface transfer coefficients. (#1242) + + +General/Technical changes +------------------------- + + * Surface type IDs fully extended to JULES to allow extra surface configuration checks to take place. A routine to check compatible science options is now accessible to all parent models, allowing cross-namelist checking to take place once all the namelists have been read, removing the dependency on order. (#1249) + * Upgraded FLake driver to version 1.10 to include a bug fix from the FLake community and keep our copy of FLake aligned with the community code base. (#1227) + * JULES now passes sea ice surface heat flux (surf_ht_flux_sice), sea ice top melt (sice_melt) and sea ice sublimation (ei_sice) from JULES to LFRic as part of the fluxes structure. These variables, and a few others, are no longer weighted by sea ice fraction before being passed out of JULES. The weighting by sea ice fraction should be done in the parent models. (#1259) + * Made stencil used in buddy_sea option work for unstructured meshes, rather than assuming i+1, j+1 indexing will work. (#1286) + * Tidied soil code so that arguments follow UMDP3 order, and corrected some argument INTENTs. (#843) + * Streamlined standalone code dealing with input of ancillary fields. (#1256) + * In preparation for including layered soil carbon in the UM, the soil respiration returned to the UM now has an extra dimension which can potentially be used to represent layers. (#1236) + * Migration of :nml:lst:`JULES_NVEGPARM` and :nml:lst:`JULES_SURFACE_TYPES` used in LFRic to shared metadata held in jules-shared. Checking of :nml:lst:`JULES_NVEGPARM` moved to a new shared routine and added to UM. (#1272) + * Passing CABLE vars (TYPEs) from top level through to and into surf_couple layer. (#1226) + * Updated the module load of the make_jules_release script. (#1263) + + +Bugs fixed +---------- + + * Fix for precision issue whereby infiltration of rainfall into snowpack could become larger than the incident rainfall, resulting in negative large-scale rain. (#1092) + * Bug fix for persistent small snow amounts - see :nml:mem:`JULES_TEMP_FIXES::l_fix_snow_frac`. (#1279) + * Correction to the chlorophyll dependence of the oceanic albedo in the scheme of Jin et al. (2011). (#1260) + * Bug fix to allow calculation of the lw_net diagnostic. (#1270) + * Fixes to UM routines identified by the NAG compiler. (#1276) + * Corrected namelist reading to ensure that FLake can be run with urban2t and MORUSES schemes in standalone JULES. (#1277) + * Fixed bug that prevented finalisation of initial output files. (#1281) + * Introduced namelist variable :nml:mem:`JULES_RIVERS_PROPS::coordinate_file` to fix bug preventing use of file-name templating with river ancillaries. (#1287) + * Prevent faults caused by attempting to read an absent dummy argument. (#1292) + * Fixed benign OMP bug in snowpack_mod. (#1304) + + +Changes to testing +------------------ + + * Added rose stem test for the FLake lake model. (#1277) + * Altered the eraint rose stem apps to better represent river routing. (#1299) + * Increased resources requested for build in Met Office XC40 rose stem. (#1291) + * Changes to module load, mpiexec usage, and memory requested for rose stem for the Met Office EXZ platform. (#1296, 1302, 1305, 1309) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes and to module leaders file, and release notes. (#1275, 1300) + +Documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES7-1.rst b/doc/source/release_notes/JULES7-1.rst new file mode 100644 index 00000000..a0357852 --- /dev/null +++ b/doc/source/release_notes/JULES7-1.rst @@ -0,0 +1,53 @@ +JULES version 7.1 Release Notes +=============================== + +The JULES vn7.1 release consists of approximately 20 tickets from 18 authors, including work by many other people. + +Full details of the tickets committed for JULES vn7.1 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #931. + + +Science changes +--------------- + + * Interactive gas-phase deposition routines from UKCA have been added to JULES, together with a variant version that removes the restriction on the surface tile configuration. See :nml:mem:`JULES_DEPOSITION::dry_dep_model`. (#931) + + +General/Technical changes +------------------------- + + * Added a switch to allow interpretation of times in the model and the driving data as local solar time - see :nml:mem:`JULES_TIME::l_local_solar_time`. (#1327) + * Added a switch :nml:mem:`IMOGEN_RUN_LIST::l_drive_with_global_temps` so that JULES can be driven with global temperatures and climate patterns. (#1322) + * Made Medlyn stomatal conductance, Farquhar C\ :sub:`3` photosynthesis, and thermal acclimation available in the UM. (#1246) + * Further work towards allowing layered soil carbon (:nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = TRUE ) in the UM. (#1237) + * A varying grey tile emissivity has been passed in to JULES - currently only available if selected in LFRic. (#1247) + * OMP improvements in various routines. (#1310) + * Enabled a call to CABLE albedo (part of ongoing work to provide access to CABLE). (#1314) + * MORUSES and anthropogenic heat related metadata migrated to jules-shared to facilitate their implementation in LFRic. The simple two-tile urban scheme now no longer requires W/R as an input unless the total urban fraction only is specified in the ancillary data. (#1255) + * Included the fab_jules app which builds JULES using Fab software. (#1331, 1364) + * Updated compiler in JASMIN gfortran platform file. (#1347) + * Upgraded rose stem testing on Met Office EXZ to use latest availiable CPE, and fixes for EXZ. (#1362, 1358) + + +Bugs fixed +---------- + + * Corrected a bug in the `surf_ht_flux` diagnostic when using the Flake lake model. (#1340) + * Fixing problems in the WARNING output messages. (#1303) + * Fixed a metadata/rose config error introduced by a bug in Rose. (#1363) + + +Changes to testing +------------------ + + * Updated NCI rose stem tests. (#1266) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes and to module leaders file, and release notes. (#1275, 1343) + +Documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES7-2.rst b/doc/source/release_notes/JULES7-2.rst new file mode 100644 index 00000000..cd770894 --- /dev/null +++ b/doc/source/release_notes/JULES7-2.rst @@ -0,0 +1,49 @@ +JULES version 7.2 Release Notes +=============================== + +The JULES vn7.2 release consists of approximately 19 tickets from 17 authors, including work by many other people. + +Full details of the tickets committed for JULES vn7.2 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #1317. + + +General/Technical changes +------------------------- + + * Switch :nml:mem:`JULES_LATLON::l_coord_latlon` specifies if the coordinate system is latitude-longitude or something else (e.g. a rotated grid). This makes it easier to model and postprocess grids that are not defined by latitude and longitude. (#1317) + * Addition of OASIS coupling capabilities to the river routing executable. (#1191) + * The RothC soil C model is now referred to as the 4-pool model. (#1348) + * Removed the remaining 2D field being passed into JULES via a module, replacing it with an argument list variable. (#1376) + * Removed a redundant print statement from the urban code. (#1367) + * Updated CABLE (as part of consolidating CABLE across its main applications, ACCESS-CM2, ESM1.5 and CABLE standalone), also corrected an inconsistency in the order of arguments for a few subroutines. (#1373) + * Increase compile-time checking with Cray's CCE. (#1061) + * Updated configuration for NIWA. (#1387) + + +Bugs fixed +---------- + + * Improved numerical implementation of an EXP calculation in the spectral albedo scheme. (#1189) + * Full initialisation of soil carbon arrays used with the INFERNO fire model. (#1356) + * Fixed the upgrde macro chain. (#1368) + * Fixes to umdp3_checker. (#1397) + + +Changes to testing +------------------ + + * Rose stem testing extended to include overbank inundation. (#999) + * loobos_gl4_cable now generates output files and is included in rose stem testing at several sites. (#1375) + * Updated suite_report.py and changed rosestem_branch_checker.py to use generic variable names to match the UKCA version. (#1369, 1379) + * Refactored rose stem tests for building JULES with FAB. (#1354) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#1381) + * Updated JULES docs to ensure that they build with a more recent version of Sphinx - they can now be built using Sphinx 2.4.0 and Python 3.6.10. (#1382) + +Documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES7-3.rst b/doc/source/release_notes/JULES7-3.rst new file mode 100644 index 00000000..b9c059b8 --- /dev/null +++ b/doc/source/release_notes/JULES7-3.rst @@ -0,0 +1,48 @@ +JULES version 7.3 Release Notes +=============================== + +The JULES vn7.3 release consists of approximately 19 tickets from 9 authors, including work by many other people. + +Full details of the tickets committed for JULES vn7.3 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #1180. + + +General/Technical changes +------------------------- + + * Removed default numerical values from variables in the :nml:lst:`JULES_HYDROLOGY` and :nml:lst:`JULES_RIVERS` namelists. (#1180) + * Allow a model domain that straddles the edge of the input grid (for grids that are cyclic in longitude). (#1301) + * Simplification of the namelists required for OASIS-Rivers to aid maintenance of the LFRic coupled miniapp. (#1385) + * Water resource variables bundled in a new TYPE. (#1401) + * Clarification of timestep-related variables. (#1403) + * Change kind type names to avoid clash with Fortran intrinsics. (#1408) + * Removed some include files by moving code to module files. (#1411, 1412. 1418) + + +Bugs fixed +---------- + + * Fixed standalone diagnostics `sat_excess_roff` and `drain`. (#1039) + * Fix for possible floating point exceptions in veg2 code. (#1155) + * Bug fixes for irrigation code. (#1386) + * Bug fixes for OASIS-Rivers coupling field, `rflow_outflow`. (#1435) + + +Changes to testing +------------------ + + * Updated `suite_report.py`. (#1442) + + +Documentation updates +--------------------- + + * Simplified the description of platform files. (#1353) + * Minor syntax changes in the JULES Coding Standards. (#1402) + * Minor corrections to code and documentation. (#1421, 1443) + * Updates associated with many of the above changes, and release notes. (#1384) + + +Documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES7-4.rst b/doc/source/release_notes/JULES7-4.rst new file mode 100644 index 00000000..7f46dd60 --- /dev/null +++ b/doc/source/release_notes/JULES7-4.rst @@ -0,0 +1,56 @@ +JULES version 7.4 Release Notes +=============================== + +The JULES vn7.4 release consists of approximately 23 tickets from 17 authors, including work by many other people. + +Full details of the tickets committed for JULES vn7.4 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #1344. + + +Science changes +------------------------- + + * Implementated the SUGAR carbohydrate model as an alternative method for calculating plant respiration - see :nml:mem:`JULES_VEGETATION::l_sugar`. (#1344) + + +General/Technical changes +------------------------- + + * Refactored the river grid setup code, including changes to the :nml:lst:`JULES_RIVERS_PROPS` namelist (#1172, 1472) + * The parameterisation of overbank inundation is now selected via the variable :nml:mem:`JULES_OVERBANK::overbank_model`. (#1405) + * Added a diagnostic of Net Biosphere Productivity for JULES and UM, and enabled diagnostics of fire emissions for output via STASH. (#1462) + * Added prognostic variables for the RED vegetation model to model dump files. (#1230) + * Adding water tracers to the surface scheme - the first stage of adding water tracers/isotopes to JULES. (#1390) + + +Bugs fixed +---------- + + * Bug fix for when deciding if surface fractions are non-zero in the initial conditions. (#1451) + * Fixes for atmospheric dry deposition. (#1332) + * Fixed bug in calculation of stem nitrogen with RED. (#1306) + * Corrected the variable fluxes%fqw_surft (moisture flux on land surface tiles) coming out of JULES and being passed to LFRic. (#1360) + * Fixing problems when JULES is coupled to the UM and layered soil nitrogen is required (:nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` and :nml:mem:`JULES_VEGETATION::l_nitrogen` are TRUE). (#1463) + * Fixed some OpenMP non-thread-safe issues with the ancil_info module. (#1450) + * Removed spurious metadata directories. (#1469) + + +Changes to testing +------------------ + + * Added rose stem tests for a spatial version of the land surface configuration used in UKESM. (#1430, 1478) + * Corrections to some rose stem tests related to deposition. (#1470) + * JULES apps were edited to ensure they can validate, and rose-stem now automatically validates new apps. (#1441, 1464) + * Check for modifications to files shared with LFRic and state requirement for LFRic testing in trac.log. (#1445) + * Update standalone rose stem configuration on Met Office EXZ system. (#1453) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#1467) + + +Documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES7-5.rst b/doc/source/release_notes/JULES7-5.rst new file mode 100644 index 00000000..dbcf37d6 --- /dev/null +++ b/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_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) + * 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/doc/source/release_notes/JULES7-6.rst b/doc/source/release_notes/JULES7-6.rst new file mode 100644 index 00000000..5d004e24 --- /dev/null +++ b/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/doc/source/release_notes/JULES7-7.rst b/doc/source/release_notes/JULES7-7.rst new file mode 100644 index 00000000..2ed02a59 --- /dev/null +++ b/doc/source/release_notes/JULES7-7.rst @@ -0,0 +1,37 @@ +JULES version 7.7 Release Notes +=============================== + +The JULES vn7.7 release consists of approximately 7 tickets from 5 authors, including work by many other people. + +Full details of the tickets committed for JULES vn7.7 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #1000. + +General/Technical changes +------------------------- + + * Initialisation related to the CaMa-Flood model of river routing and inundation. Note that this model is still in development and cannot yet be used. (#1000) + * Developments to allow the blending height to be increased and passed between timesteps - for use with the UM atmospheric model. (#1500) + +Bugs fixed +---------- + + * Fix for a bug that prevented the calculation of time-mean river-point variables in MPI runs. (#1544) + * Enable the lake_evap field to be populated in LFRic-based models, even when river routing is not selected. (#1546) + + +Changes to testing +------------------ + + * Correct PBS directives used for runs on Met Office EX platforms. (#1547) + + +Documentation updates +--------------------- + + * Included a set of changes previously missed. (#1559) + * Updates associated with many of the above changes, and release notes. (#1567) + + +Documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES7-8.rst b/doc/source/release_notes/JULES7-8.rst new file mode 100644 index 00000000..92d480c5 --- /dev/null +++ b/doc/source/release_notes/JULES7-8.rst @@ -0,0 +1,41 @@ +JULES version 7.8 Release Notes +=============================== + +The JULES vn7.8 release consists of approximately 12 tickets from 7 authors, including work by many other people. + +Full details of the tickets committed for JULES vn7.8 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #1565. + +General/Technical changes +------------------------- + + * Introduced a daily climatology (alongside existing monthly) option for IMOGEN using a 360 day calendar - see :nml:mem:`IMOGEN_ONOFF_SWITCH::l_daily_metdata_climatol`. Also changes to the IMOGEN options to clarify the different ways they drive JULES - see :nml:mem:`IMOGEN_RUN_LIST::l_change_metdata` and :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method`. (#1565) + * Functionality added to allow specification of the ancillary file that each of the required ancillary variables should be read from. (#1525) + * Diagnostics for RFM river routing now available in the UM atmosphere model. (#1555) + * Allowing JULES to be used on the Met Office's Azspice system. Change to the default EX machine for rose stem and allowing use of EXCD. (#1576, 1580, 1585) + * Updates for the upgraded JASMIN system. (#1586) + + +Bugs fixed +---------- + + * Fix for dry deposition on elevated tiles. (#1568) + * Bug fix for fire-permafrost interactions in the UM (altered the upper limit when checking value of z_burn_max). (#1581) + * Bug fix to avoid zero lengths being calculated for a high resolution river grid. (#1583) + + +Changes to testing +------------------ + + * Additional rose stem tests for IMOGEN. (#1566) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#1584) + + +Documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES7-9.rst b/doc/source/release_notes/JULES7-9.rst new file mode 100644 index 00000000..e761122f --- /dev/null +++ b/doc/source/release_notes/JULES7-9.rst @@ -0,0 +1,54 @@ +JULES version 7.9 Release Notes +=============================== + +The JULES vn7.9 release consists of approximately 18 tickets from 12 authors, including work by many other people. + +Full details of the tickets committed for JULES vn7.9 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #1590. + + +Science changes +--------------- + + * Additional scheme for soil uptake of H\ :sub:`2` from the atmosphere - see :nml:mem:`JULES_DEPOSITION::dep_h2_soil_scheme`. (#1590) + + +General/Technical changes +------------------------- + + * Add variables to a namelist and a logical switch for the Robust Ecosystem Demography code. (#1425) + * Add further parameters for the Random Parameter scheme used in regional ensemble forecasting. (#1439) + * Allow the MORUSES canyon emissivity to be set externally via the switch `l_emis_surft_set`, as for other tiles. (#1597) + * Avoid creation of temporary arrays. (#1595, 1606) + * The INFERNO coupling framework was extended to pass additional INFERNO-derived emissions to the UKCA chemistry and aerosol model of C\ :sub:`2`\ H\ :sub:`4`, C\ :sub:`2`\ H\ :sub:`6`, C\ :sub:`3`\ H\ :sub:`8`, HCHO, MeCHO, NH\ :sub:`3` and DMS. (#1579) + * All metadata items ported to LFRic now reside in jules-shared and have been deleted from um-atmos. (#1588) + * Allow JULES to build using Fab on azspice at the Met Office. (#1596) + * Provide a set up for rivers-only jobs on the Met Office EX machines. (1598) + + +Bugs fixed +---------- + + * Bug fix to prevent possible array-bounds error when reading a list of ancillary file names from file. (#1607) + * Tidy the use of USE with LFRic. (#1604) + * Fix to enable rivers coupled to LFRic to run on the EX machines at Met Office. (#1608) + + +Changes to testing +------------------ + + * Add a remote initialisation task as part of moving to cylc8. (#1605) + * Allow rose stem to use both EX Host Zones at Met Office. (#1599) + * Fix for rose stem on azspice at Met Office. (#1600) + * Remove spice and xc40 rose-stem set ups. (#1602) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#1613) + + +Documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/JULES8-0.rst b/doc/source/release_notes/JULES8-0.rst new file mode 100644 index 00000000..625ebae7 --- /dev/null +++ b/doc/source/release_notes/JULES8-0.rst @@ -0,0 +1,47 @@ +JULES version 8.0 Release Notes +=============================== + +The JULES vn8.0 release consists of approximately 10 tickets from 7 authors, including work by many other people. This is the first release for which the JULES code is held on GitHub. + +Full details of the tickets committed for JULES vn8.0 can be found on the `JULES shared repository Trac system `_. + +Ticket numbers are indicated below, e.g. #1088. + + +Science changes +--------------- + + * Demands for water for human uses can be met from local water sources (surface and ground waters) - see :nml:lst:`JULES_WATER_RESOURCES`. (#1088) + * Added option for urban anthropogenic heat flux with diurnal and latitude-dependent annual cycles following the scheme of Flanner (2009) - see :nml:mem:`JULES_SURFACE::anthrop_heat_option`. (#1371) + + +General/Technical changes +------------------------- + + * River storage can be initialised from a 12-month climatological ancillary file (motivated by the needs of LFRic coupled modelling) - see :nml:lst:`JULES_RIVERS_PROPS`. (#1392) + * The river number ancillary (used for coupling to the ocean model) has been updated with one consistent with the river routing ancillary. They now pass the rivers ancillary checking routine, hence `l_ignore_ancil_rivers_check` has been removed. (#1460) + * Code for CABLE removed for licensing purposes. The CABLE code will only reside within its own repository and will be included at compilation time in future releases. (#1633) + + +Bugs fixed +---------- + + * An upgrade macro that was missied from the previous release has been added. (#1619) + * Removed default diagnostic flags used for LFRic. (#1627) + + +Changes to testing +------------------ + + * Cylc7 deprecated for rose-stem testing. (#1564) + * Modified usage of umdp3_fixer.py. (#1635) + + +Documentation updates +--------------------- + + * Updates associated with many of the above changes, and release notes. (#1638) + + +Documentation can be viewed on the github page ``_. + diff --git a/doc/source/release_notes/contents.rst b/doc/source/release_notes/contents.rst new file mode 100644 index 00000000..a2f6186d --- /dev/null +++ b/doc/source/release_notes/contents.rst @@ -0,0 +1,52 @@ +============= +Release notes +============= + +.. toctree:: + JULES8-0 + JULES7-9 + JULES7-8 + JULES7-7 + JULES7-6 + JULES7-5 + JULES7-4 + JULES7-3 + JULES7-2 + JULES7-1 + JULES7-0 + JULES6-3 + JULES6-2 + JULES6-1 + JULES6-0 + JULES5-9 + JULES5-8 + JULES5-7 + JULES5-6 + JULES5-5 + JULES5-4 + JULES5-3 + JULES5-2 + JULES5-1 + JULES5-0 + JULES4-9 + JULES4-8 + JULES4-7 + JULES4-6 + JULES4-5 + JULES4-4 + JULES4-3 + JULES4-2 + JULES4-1 + JULES4-0 + JULES3-4 + JULES3-3 + JULES3-2 + JULES3-1 + JULES3-0 + JULES2-2 + JULES2-1 + JULES2-0 + JULES1-0 + +For further information about these releases, please see `here `__. + diff --git a/doc/sphinxext/pygments_fcm_make_conf_lexer.py b/doc/sphinxext/pygments_fcm_make_conf_lexer.py new file mode 100644 index 00000000..01409aff --- /dev/null +++ b/doc/sphinxext/pygments_fcm_make_conf_lexer.py @@ -0,0 +1,65 @@ +# -*- coding: utf-8 -*- +""" + FCM make configuration file lexer for Pygments +""" + +from pygments.lexer import RegexLexer, bygroups +from pygments.token import * + + +class FCMMakeConfLexer(RegexLexer): + """Pygments lexer for FCM make configuration files""" + name = 'FCM make' + aliases = ['fcm_make'] + filenames = ['*.cfg'] + + tokens = { + 'root': [ + # Consume any runs of whitespace as normal text + (r'\s+', Text), + + # Anything from # to the end of a line is a comment + (r'#.*$', Comment.Single), + + # Anything starting with a $ is a variable + # Variables can optionally be appended with {?} to indicate that they can be set as environment variables + (r'(\$[\w-]+)(\{\?\})?', bygroups(Name.Variable, Punctuation)), + + # Anything consisting of only alphanumeric characters (plus .) is rendered as a namespace + (r'[\w\-_\.]+', Keyword.Namespace), + + # Anything between {} is rendered as a tag + (r'(\{)([\w\-_\.]+)(\})', bygroups(Punctuation, Name.Tag, Punctuation)), + + # Anything between [] is rendered as a class + (r'(\[)([\w\-_\.\/]+)(\])', bygroups(Punctuation, Name.Class, Punctuation)), + + # Use a catch-all for anything on the left of an equals sign not already covered + (r'[\w\-\.\{\}\[\]/\?]+(?=\s*=)', Name.Property), + + # = is an operator that puts us into a 'value' state + (r'=', Operator, 'value'), + ], + + 'value' : [ + # Spans of spaces and tabs are treated as normal text + (r'[ \t]+', Text), + + # Whitespace followed by "\" followed by a newline is treated as text, special punctuation then text + (r'([ \t]*)(\\)([ \t]*\n)', bygroups(Text, Punctuation, Text)), + + # Anything starting with a $ is an embedded variable + (r'\$[\w-]+', Name.Variable), + + # Anything not whitespace, "$" or "\" is treated as a string + (r'[^\s\\\$]+', String.Double), + + # A newline with no \ is rendered as text, but kicks us back into root + (r'\n', Text, '#pop'), + ] + } + + +def setup(app): + """Makes the lexer known to Pygments through Sphinx""" + app.add_lexer('fcm_make', FCMMakeConfLexer) \ No newline at end of file diff --git a/doc/sphinxext/pygments_fortran_nml_lexer.py b/doc/sphinxext/pygments_fortran_nml_lexer.py new file mode 100644 index 00000000..fa182036 --- /dev/null +++ b/doc/sphinxext/pygments_fortran_nml_lexer.py @@ -0,0 +1,59 @@ +# -*- coding: utf-8 -*- +""" + Fortran namelist lexer for Pygments +""" + +from pygments.lexer import RegexLexer +from pygments.token import Text, Comment, Operator, Name, String, \ + Number, Punctuation + + +class FortranNmlLexer(RegexLexer): + """Pygments lexer for Fortran Namelists""" + name = 'Fortran Namelists' + aliases = ['nml'] + filenames = ['*.nml'] + + tokens = { + 'root': [ + # Consume any runs of whitespace as normal text + (r'\s+', Text), + + # Anything from ! or # to the end of a line is rendered as a comment + (r'[#!].*$', Comment.Single), + + # Check for constants next, as some things that might be interpreted as variable name might be in here (i.e. T/F for logicals) + # String literals + (r'\'[^\']*\'', String.Single), + (r'"[^"]*"', String.Double), + # Logicals + # .TRUE./.FALSE. form + (r'(?i)\.(true|false)\.', String.Symbol), + # T/F form (i.e. a T or an F followed by any non-alpha-numeric character + (r'(?i)[tf](?=[^\w])', String.Symbol), + # Real numbers, with optional sign, optional integer part and optional exponent + (r'[+-]?\d*\.\d+([eE][+-]?\d+)?', Number.Float), + # Integers with optional sign + (r'[+-]?\d+', Number.Integer), + + # Match a namelist identifier as a namespace + (r'&\w+', Name.Namespace), + + # Also match namelist terminators as namespace objects so they match the namespace identifiers + (r'/', Name.Namespace), + + # Any run of alphanumeric characters not in quotes is treated as a variable name + (r'[a-zA-Z]\w*', Name.Variable), + + # = is the assignment operator, % is the "structure member" operator and : is the range operator + (r'[\*=%:]', Operator), + + # Significant punctuation + (r'[\(\),]', Punctuation), + ] + } + + +def setup(app): + """Makes the lexer known to Pygments through Sphinx""" + app.add_lexer('nml', FortranNmlLexer) \ No newline at end of file diff --git a/doc/sphinxext/sphinx_nml_domain.py b/doc/sphinxext/sphinx_nml_domain.py new file mode 100644 index 00000000..51fbd1b7 --- /dev/null +++ b/doc/sphinxext/sphinx_nml_domain.py @@ -0,0 +1,355 @@ +# -*- coding: utf-8 -*- +""" + Fortran namelist domain +""" + +import re + +from docutils import nodes +from docutils.parsers.rst import directives, Directive +from docutils.parsers.rst.directives.admonitions import BaseAdmonition + +from sphinx import addnodes +from sphinx.roles import XRefRole +from sphinx.locale import _ +from sphinx.domains import Domain, ObjType, Index +from sphinx.directives import ObjectDescription +from sphinx.util.nodes import make_refnode +from sphinx.util.docfields import Field + + +class MemberDirective(ObjectDescription): + """ + Description of a Fortran namelist member object (like a Python function). + """ + option_spec = { + 'noindex': directives.flag, + 'module': directives.unchanged, + } + + doc_field_types = [ + Field('type', label=_('Type'), has_arg=False, names=('type')), + Field('permitted', label=_('Permitted'), has_arg=False, names=('permitted')), + Field('default', label=_('Default'), has_arg=False, names=('default')), + ] + + def get_signature_prefix(self, sig): + """ + May return a prefix to put before the object name in the signature. + """ + return '' + + def needs_arglist(self): + """ + May return true if an empty argument list is to be generated even if + the document contains none. + """ + return False + + def handle_signature(self, sig, signode): + """ + Transform a member signature into RST nodes. + Returns fully qualified name of the thing. + """ + if sig is None: + raise ValueError + + # The signature is just the member name + name = sig + + # Determine namelist name (if applicable), as well as full name + nmlname = self.options.get('namelist', self.env.temp_data.get('nml:namelist')) + + fullname = nmlname + '::' + name + + signode['namelist'] = nmlname + signode['fullname'] = fullname + + if self.env.config.add_module_names: + nodetext = nmlname + '::' + signode += addnodes.desc_addname(nodetext, nodetext) + + signode += addnodes.desc_name(name, name) + return fullname + + def add_target_and_index(self, name, sig, signode): + nmlname = self.options.get('namelist', self.env.temp_data.get('nml:namelist')) + + prefix = nmlname and nmlname + '::' or '' + + fullname = name if '::' in name else nmlname + '::' + name + + # note target + if fullname not in self.state.document.ids: + signode['names'].append(fullname) + signode['ids'].append(fullname) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + objects = self.env.domaindata['nml']['objects'] + if fullname in objects: + self.env.warn( + self.env.docname, + 'duplicate object description of %s, ' % fullname + + 'other instance in ' + + self.env.doc2path(objects[fullname][0]), + self.lineno) + objects[fullname] = (self.env.docname, self.objtype) + + # For the index text, strip the namelist name from the fully qualified name + indextext = _('%s (in namelist %s)') % (name.split('::')[1] if '::' in name else name, nmlname) + + if indextext: + self.indexnode['entries'].append(('single', indextext, fullname, fullname, None)) + + +class NamelistDirective(Directive): + """ + Directive to start a new Fortran namelist. + Namelists are like Python modules - they are invisible but add context to namelist members + """ + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'synopsis': lambda x: x, + 'noindex': directives.flag, + 'deprecated': directives.flag, + } + + def run(self): + env = self.state.document.settings.env + nmlname = self.arguments[0].strip() + noindex = 'noindex' in self.options + env.temp_data['nml:namelist'] = nmlname + env.domaindata['nml']['namelists'][nmlname] = ( + env.docname, self.options.get('synopsis', ''), + 'deprecated' in self.options) + + targetnode = nodes.target('', '', ids=['namelist-' + nmlname], ismod=True) + self.state.document.note_explicit_target(targetnode) + ret = [targetnode] + + # the synopsis isn't printed; in fact, it is only used in the + # modindex currently + if not noindex: + indextext = _('%s (namelist)') % nmlname + inode = addnodes.index(entries=[('single', indextext, 'namelist-' + nmlname, nmlname, None)]) + ret.append(inode) + + return ret + + +class NamelistMemberGroupDirective(BaseAdmonition): + """ + An admonition type construct for namelist members that form a logical group + Adds no extra context - for semantic purposes in ReST markup only + """ + required_arguments = 1 + node_class = nodes.admonition + + +class NamelistXRefRole(XRefRole): + """ + Provides cross reference links for namelists + """ + def process_link(self, env, refnode, has_explicit_title, title, target): + # The target is a namelist, regardless of whether it has been defined yet + refnode['nml:namelist'] = target + + # If an explicit title is not given, just use the member name, not the namelist name + if not has_explicit_title: + title = target + + return title, target + + +class NamelistMemberXRefRole(XRefRole): + """ + Provides cross reference links for namelist members + """ + def process_link(self, env, refnode, has_explicit_title, title, target): + # If the target contains a separator, then it is a member target + if '::' in target: + # Extract the target namelist name, leave the target unchanged + target_nml, _ = target.split('::') + # If the target does not contain a separator, interpret it as a member reference in the current namelist context + else: + target_nml = env.temp_data.get('nml:namelist') + # If there was no target nml (i.e. we are not in a namelist scope...) then leave the target untouched + # It will be rendered as an unresolved link + target = target_nml + '::' + target if target_nml else target + + refnode['nml:namelist'] = target_nml + + # If an explicit title is not given, just use the member name, not the namelist name + if not has_explicit_title: + title = target.split('::')[1] if '::' in target else target + + return title, target + + +class NamelistIndex(Index): + """ + Index subclass to provide the Fortran namelist index. + """ + + name = 'modindex' + localname = _('Fortran Namelist Index') + shortname = _('namelists') + + def generate(self, docnames = None): + content = {} + # list of prefixes to ignore + ignores = self.domain.env.config['modindex_common_prefix'] + ignores = sorted(ignores, key=len, reverse=True) + # list of all modules, sorted by module name + modules = sorted(self.domain.data['namelists'].items(), key=lambda x: x[0].lower()) + # sort out collapsable modules + prev_modname = '' + num_toplevels = 0 + for modname, (docname, synopsis, deprecated) in modules: + if docnames and docname not in docnames: + continue + + for ignore in ignores: + if modname.startswith(ignore): + modname = modname[len(ignore):] + stripped = ignore + break + else: + stripped = '' + + # we stripped the whole module name? + if not modname: + modname, stripped = stripped, '' + + entries = content.setdefault(modname[0].lower(), []) + + package = modname.split('::')[0] + if package != modname: + # it's a submodule + if prev_modname == package: + # first submodule - make parent a group head + entries[-1][1] = 1 + elif not prev_modname.startswith(package): + # submodule without parent in list, add dummy entry + entries.append([stripped + package, 1, '', '', '', '', '']) + subtype = 2 + else: + num_toplevels += 1 + subtype = 0 + + qualifier = deprecated and _('Deprecated') or '' + entries.append([stripped + modname, subtype, docname, + 'namelist-' + stripped + modname, '', + qualifier, synopsis]) + prev_modname = modname + + # apply heuristics when to collapse modindex at page load: + # only collapse if number of toplevel modules is larger than + # number of submodules + collapse = len(modules) - num_toplevels < num_toplevels + + # sort by first letter + content = sorted(content.items()) + + return content, collapse + + +class NamelistDomain(Domain): + """Fortran namelist domain.""" + + name = 'nml' + + label = 'Fortran namelist' + + object_types = { + 'namelist': ObjType(_('namelist'), 'lst', 'obj'), + 'member': ObjType(_('member'), 'mem', 'obj') + } + + directives = { + 'namelist': NamelistDirective, + 'group' : NamelistMemberGroupDirective, + 'member': MemberDirective + } + + roles = { + 'lst': NamelistXRefRole(), + 'mem': NamelistMemberXRefRole() + } + + initial_data = { + 'objects': {}, # fullname -> docname, objtype + 'namelists': {}, # namespace -> docname, synopsis + } + + indices = [ + NamelistIndex, + ] + + def clear_doc(self, docname): + for fullname, (fn, _) in list(self.data['objects'].items()): + if fn == docname: + del self.data['objects'][fullname] + + for nml, (fn, _, _) in list(self.data['namelists'].items()): + if fn == docname: + del self.data['namelists'][nml] + + def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + if (typ == 'lst' or typ == 'obj' and target in self.data['namelists']): + docname, synopsis, deprecated = self.data['namelists'].get(target, ('', '', '')) + + if not docname: + return None + else: + title = '%s%s' % (synopsis, (deprecated and ' (deprecated)' or '')) + return make_refnode(builder, fromdocname, docname, 'namelist-' + target, contnode, title) + else: + nmlname = node.get('nml:namelist') + searchorder = node.hasattr('refspecific') and 1 or 0 + name, obj = self.find_obj(env, nmlname, target, typ, searchorder) + + if not obj: + return None + else: + return make_refnode(builder, fromdocname, obj[0], name, contnode, name) + + def find_obj(self, env, nmlname, name, type, searchorder=0): + """ + Find a namelist object for "name", perhaps using the given namelist. + """ + if not name: + return None, None + + objects = self.data['objects'] + + newname = None + if searchorder == 1: + if nmlname and nmlname + '::' + name in objects: + newname = nmlname + '::' + name + elif name in objects: + newname = name + else: + if name in objects: + newname = name + elif nmlname and nmlname + '::' + name in objects: + newname = nmlname + '::' + name + + if newname is None: + return None, None + + return newname, objects[newname] + + def get_objects(self): + for nml, info in self.data['namelists'].items(): + yield (nml, nml, 'namelist', info[0], 'namelist-' + nml, 0) + + for refname, (docname, type) in self.data['objects'].items(): + yield (refname, refname, type, docname, refname, 1) + + +def setup(app): + app.add_domain(NamelistDomain) From c496463b018431fd4072744f78be71a2da206d91 Mon Sep 17 00:00:00 2001 From: Yaswant Pradhan <2984440+yaswant@users.noreply.github.com> Date: Tue, 25 Nov 2025 11:38:31 +0000 Subject: [PATCH 2/3] Tidy docs and workflow --- .github/scripts/release.py | 241 --------- .github/workflows/build_docs.yml | 92 ---- .github/workflows/user-guide.yaml | 72 +++ .gitignore | 14 +- README.md | 4 + doc/Makefile | 161 +----- doc/README.md | 29 ++ doc/environment.yaml | 11 + doc/pyproject.toml | 11 + doc/source/_static/jules-tweaks.css | 169 +++--- .../building-and-running/considerations.rst | 16 +- doc/source/building-and-running/fcm.rst | 40 +- doc/source/building-and-running/intro.rst | 4 +- .../required-software.rst | 9 +- doc/source/building-and-running/rose.rst | 32 +- .../building-and-running/running-jules.rst | 22 +- doc/source/code/contents.rst | 3 +- doc/source/code/io.rst | 48 +- doc/source/conf.py | 16 +- doc/source/examples.rst | 6 +- doc/source/index.rst | 18 +- doc/source/input/ascii.rst | 4 +- doc/source/input/file-name-templating.rst | 64 +-- doc/source/input/netcdf.rst | 2 +- doc/source/input/overview.rst | 2 - doc/source/input/principles.rst | 2 +- doc/source/input/temporal-interpolation.rst | 18 +- doc/source/namelists/ancillaries.nml.rst | 94 ++-- doc/source/namelists/cable_pftparm.nml.rst | 2 +- .../namelists/cable_prognostics.nml.rst | 2 +- doc/source/namelists/cable_soilparm.nml.rst | 4 - .../namelists/cable_surface_types.nml.rst | 14 +- doc/source/namelists/contents.rst | 10 +- doc/source/namelists/crop_params.nml.rst | 489 +++++++++--------- doc/source/namelists/drive.nml.rst | 301 ++++++----- doc/source/namelists/fire.nml.rst | 1 - doc/source/namelists/imogen.nml.rst | 35 +- .../namelists/initial_conditions.nml.rst | 1 - doc/source/namelists/intro.rst | 4 +- doc/source/namelists/jules_deposition.nml.rst | 16 +- doc/source/namelists/jules_hydrology.nml.rst | 6 +- doc/source/namelists/jules_irrig.nml.rst | 14 +- .../namelists/jules_prnt_control.nml.rst | 1 - doc/source/namelists/jules_radiation.nml.rst | 52 +- doc/source/namelists/jules_rivers.nml.rst | 8 +- doc/source/namelists/jules_snow.nml.rst | 64 +-- doc/source/namelists/jules_soil.nml.rst | 28 +- .../namelists/jules_soil_biogeochem.nml.rst | 16 +- .../namelists/jules_soil_ecosse.nml.rst | 38 +- doc/source/namelists/jules_surface.nml.rst | 8 +- .../namelists/jules_surface_types.nml.rst | 313 +++++------ doc/source/namelists/jules_vegetation.nml.rst | 101 ++-- .../namelists/jules_water_resources.nml.rst | 4 +- .../namelists/model_environment.nml.rst | 9 +- doc/source/namelists/model_grid.nml.rst | 277 +++++----- doc/source/namelists/output.nml.rst | 2 - doc/source/namelists/pft_params.nml.rst | 28 +- doc/source/namelists/prescribed_data.nml.rst | 112 ++-- doc/source/namelists/red_parms.nml.rst | 39 +- doc/source/namelists/science_fixes.nml.rst | 17 +- doc/source/namelists/timesteps.nml.rst | 8 +- doc/source/namelists/triffid_params.nml.rst | 12 +- doc/source/namelists/urban.nml.rst | 13 +- doc/source/output-variables.rst | 37 +- doc/source/output.rst | 6 +- doc/source/overview/intro.rst | 3 +- doc/source/overview/key-switches.rst | 57 +- doc/source/overview/overview.rst | 35 +- doc/source/release_notes/JULES3-0.rst | 2 +- doc/source/release_notes/JULES3-1.rst | 4 +- doc/source/release_notes/JULES3-3.rst | 10 +- doc/source/release_notes/JULES3-4.rst | 2 +- doc/source/release_notes/JULES4-0.rst | 6 +- doc/source/release_notes/JULES4-1.rst | 8 +- doc/source/release_notes/JULES4-8.rst | 2 +- doc/source/release_notes/JULES4-9.rst | 2 +- doc/source/release_notes/JULES5-0.rst | 2 +- doc/source/release_notes/JULES5-1.rst | 2 +- doc/source/release_notes/JULES5-2.rst | 4 +- doc/source/release_notes/JULES5-3.rst | 2 +- doc/source/release_notes/JULES5-4.rst | 2 +- doc/source/release_notes/JULES5-6.rst | 2 +- doc/source/release_notes/JULES5-7.rst | 2 +- doc/source/release_notes/JULES5-8.rst | 2 +- doc/source/release_notes/JULES5-9.rst | 2 +- doc/source/release_notes/JULES6-0.rst | 2 +- doc/source/release_notes/JULES6-1.rst | 4 +- doc/source/release_notes/JULES6-2.rst | 4 +- doc/source/release_notes/JULES6-3.rst | 4 +- doc/source/release_notes/JULES7-0.rst | 2 +- doc/source/release_notes/JULES7-1.rst | 38 +- doc/source/release_notes/JULES7-2.rst | 2 +- doc/source/release_notes/JULES7-3.rst | 2 +- doc/source/release_notes/JULES7-4.rst | 2 +- doc/source/release_notes/JULES7-5.rst | 2 +- doc/source/release_notes/JULES7-6.rst | 4 +- doc/source/release_notes/JULES7-7.rst | 2 +- doc/source/release_notes/JULES7-8.rst | 2 +- doc/source/release_notes/JULES7-9.rst | 2 +- doc/source/release_notes/JULES8-0.rst | 7 +- 100 files changed, 1620 insertions(+), 1906 deletions(-) delete mode 100755 .github/scripts/release.py delete mode 100644 .github/workflows/build_docs.yml create mode 100644 .github/workflows/user-guide.yaml create mode 100644 README.md create mode 100644 doc/README.md create mode 100644 doc/environment.yaml create mode 100644 doc/pyproject.toml diff --git a/.github/scripts/release.py b/.github/scripts/release.py deleted file mode 100755 index 6e1f148a..00000000 --- a/.github/scripts/release.py +++ /dev/null @@ -1,241 +0,0 @@ -#!/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'    \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) - - # Push the update to the upstream repo and branch - cmd = ["git", "push", "--force", "origin"] - if args.gh_pages: - cmd.append("gh-pages") - run(cmd, check=True) - logging.info("Pushed automatic commit") - - 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.""" - - 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( - "--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() - - 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: - if args.gh_pages: - 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: - 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 deleted file mode 100644 index be1ccc3c..00000000 --- a/.github/workflows/build_docs.yml +++ /dev/null @@ -1,92 +0,0 @@ ---- -# 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 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 - -# Controls when the action will run -on: - push: - branches: [master] - 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 - with: - fetch-depth: 0 - fetch-tags: true - - - name: Setup conda - run: | - conda update conda - 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 build test passed" >> $GITHUB_STEP_SUMMARY - else - echo ":x: Documentation build test failed" >> $GITHUB_STEP_SUMMARY - exit 1 - fi - if make linkcheck; then - echo ":heavy_check_mark: Documentation link checking passed" >> $GITHUB_STEP_SUMMARY - else - echo ":x: Documentation link checking failed" >> $GITHUB_STEP_SUMMARY - 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 - - # 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 --gh-pages $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') }} diff --git a/.github/workflows/user-guide.yaml b/.github/workflows/user-guide.yaml new file mode 100644 index 00000000..901d1fe6 --- /dev/null +++ b/.github/workflows/user-guide.yaml @@ -0,0 +1,72 @@ +name: User Guide + +on: + push: + branches: + - main + pull_request: + types: [opened, reopened, synchronize] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + timeout-minutes: 5 + env: + PYTHON_VRSN: '3.13' + VENV_PATH: 'doc/.venv' + + steps: + - name: Checkout repository + uses: actions/checkout@v6 + + - name: Setup uv with Python ${{ env.PYTHON_VRSN }} + uses: astral-sh/setup-uv@v7 + with: + python-version: ${{ env.PYTHON_VRSN }} + + - name: Cache uv venv + uses: actions/cache@v4 + with: + path: ${{ env.VENV_PATH }} + key: ${{ runner.os }}-uv-${{ env.PYTHON_VRSN }}-${{ hashFiles('pyproject.toml') }} + restore-keys: | + ${{ runner.os }}-uv-${{ env.PYTHON_VRSN }}- + + - name: Install dependencies + working-directory: ./doc + run: uv sync + + - name: Lint Sphinx docs + working-directory: ./doc + run: uv run sphinx-lint source + + - name: Build HTML docs + working-directory: ./doc + run: uv run make clean html + + - name: Minimize uv cache + run: uv cache prune --ci + + # -- Deploy to GitHub Pages only on push to upstream main + - name: Setup GitHub Pages + if: ${{ github.ref_name == 'main' && (github.event_name == 'push' || github.event_name == 'merge_group') }} + uses: actions/configure-pages@v5 + + - name: Upload artifact to GitHub Pages + if: ${{ github.ref_name == 'main' && (github.event_name == 'push' || github.event_name == 'merge_group') }} + uses: actions/upload-pages-artifact@v4 + with: + name: github-pages + path: doc/build/html + retention-days: 1 + + - name: Deploy to GitHub Pages + id: deployment + if: ${{ github.ref_name == 'main' && (github.event_name == 'push' || github.event_name == 'merge_group') }} + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 6e0f858c..99a605ff 100644 --- a/.gitignore +++ b/.gitignore @@ -5,16 +5,16 @@ results/*.txt processed_data/*.dat .*.sw? -#ignore build output -/build/ -_build/ +# ignore build output +*build/ +*_build/ user_guide/doc/_build user_guide/doc/build -#ignore VS Code files +# ignore VS Code files /.idea -#ignore envs +# ignore envs .env .venv env/ @@ -22,3 +22,7 @@ venv/ ENV/ env.bak/ venv.bak/ + +# UV +*uv.lock +.python-version diff --git a/README.md b/README.md new file mode 100644 index 00000000..7297442a --- /dev/null +++ b/README.md @@ -0,0 +1,4 @@ +# JULES - Joint UK Land Environment Simulator + +The Joint UK Land Environment Simulator (JULES) is a computer model that +simulates many soil and vegetation processes. diff --git a/doc/Makefile b/doc/Makefile index c360915f..feeb008c 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,153 +1,28 @@ -# Makefile for Sphinx documentation +# Minimal makefile for Sphinx documentation # -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source BUILDDIR = build -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext +REPO := $(notdir $(shell git rev-parse --show-toplevel)) +BRANCH := $(shell git rev-parse --abbrev-ref HEAD) +DEPLOYDIR = $(HOME)/public_html +# Put it first so that "make" without argument is like "make help". help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/JULESJointUKLandEnvironmentSimulator.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/JULESJointUKLandEnvironmentSimulator.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/JULESJointUKLandEnvironmentSimulator" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/JULESJointUKLandEnvironmentSimulator" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." +.PHONY: help Makefile -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." +deploy: + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(DEPLOYDIR)/$(REPO)/$(BRANCH)" $(SPHINXOPTS) $(O) -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 00000000..31e19095 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,29 @@ +# Building the JULES User Guide + +This README describes how to build the JULES User Guide. + +For first time users, please create a virtual environment to build the docs. + +From the `jules/doc` folder of the repository run: + +```sh +conda env create -f environment.yml +``` + +Activate the environment: + +```sh +conda activate jules-user-guide +``` + +Build the documentation: + +```sh +make clean html +``` + +View the documentation: + +```sh +firefox build/html/index.html +``` diff --git a/doc/environment.yaml b/doc/environment.yaml new file mode 100644 index 00000000..4e73f3d2 --- /dev/null +++ b/doc/environment.yaml @@ -0,0 +1,11 @@ +name: jules-user-guide + +channels: + - conda-forge + +dependencies: + - python=3.13.2 + - doc8>=2.0.0 + - sphinx-lint==1.0.1 + - sphinx==8.2.3 + diff --git a/doc/pyproject.toml b/doc/pyproject.toml new file mode 100644 index 00000000..54fee1ce --- /dev/null +++ b/doc/pyproject.toml @@ -0,0 +1,11 @@ +[project] +name = "jules" +version = "0.1.0" +description = "Add your description here" +readme = "README.md" +requires-python = ">=3.13" +dependencies = [ + "doc8>=2.0.0", + "sphinx==8.2.3", + "sphinx-lint==1.0.1", +] diff --git a/doc/source/_static/jules-tweaks.css b/doc/source/_static/jules-tweaks.css index 55d698a5..d962860e 100644 --- a/doc/source/_static/jules-tweaks.css +++ b/doc/source/_static/jules-tweaks.css @@ -1,207 +1,214 @@ pre { - background-color : #f2f8ff; + background-color: #f2f8ff; } tt { - background-color : #f1f5f7; - border : 1px solid #C6C9CB; - padding : 2px 4px; + background-color: #f1f5f7; + border: 1px solid #c6c9cb; + padding: 2px 4px; } -dt tt:only-child { - display : inline-block; - margin-bottom : 2px; +dt tt:only-child { + display: inline-block; + margin-bottom: 2px; } -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt, a tt, dl.member dt tt { - border : 0; - padding : 0; - margin : 0; +h1 tt, +h2 tt, +h3 tt, +h4 tt, +h5 tt, +h6 tt, +a tt, +dl.member dt tt { + border: 0; + padding: 0; + margin: 0; } a tt { - color : inherit; + color: inherit; } p.rubric { - padding-top : 5px; - border-top : 1px solid #C6C9CB; - padding-left : 10px; + padding-top: 5px; + border-top: 1px solid #c6c9cb; + padding-left: 10px; } table.footnote { - margin : 0px 10px; + margin: 0px 10px; } div.sphinxsidebar { - width : 20%; + width: 20%; } div.bodywrapper { - margin : 0 0 0 20%; + margin: 0 0 0 20%; } div.sphinxsidebarwrapper { - padding-top : 10px; + padding-top: 10px; } div.sphinxsidebar p { - padding : 5px 10px; - margin-top : 0; + padding: 5px 10px; + margin-top: 0; } - /* Namelist member formatting */ dl { - margin : 0; + margin: 0; } dl > dd { - margin-top : 5px; - margin-bottom : 15px; + margin-top: 5px; + margin-bottom: 15px; } dl > dd:empty { - margin-top : 0px; - margin-bottom : 0px; + margin-top: 0px; + margin-bottom: 0px; } dl.member > dt { - font-size : 1.1em; + font-size: 1.1em; } dl.member > dd { - margin-bottom : 25px; + margin-bottom: 25px; } dl.member > dd:empty { - margin-bottom : 0px; + margin-bottom: 0px; } - /* Admonition stuff */ div.admonition { - padding : 7px 15px 15px; - border : 1px solid #C6C9CB; + padding: 7px 15px 15px; + border: 1px solid #c6c9cb; } div.admonition p.admonition-title { - position : relative; - top : -7px; - display : block; - background-color : #e1e5e7; - border-bottom : 1px solid #C6C9CB; - margin : -7px -15px 0px; - padding : 5px 15px; - font-size : 1.1em; + position: relative; + top: -7px; + display: block; + background-color: #e1e5e7; + border-bottom: 1px solid #c6c9cb; + margin: -7px -15px 0px; + padding: 5px 15px; + font-size: 1.1em; } p.admonition-title:after { - content : ""; + content: ""; } div.admonition p.admonition-title + p { - display : block; - margin-top : 5px; + display: block; + margin-top: 5px; } div.admonition p.admonition-title + * { - margin-top : 5px; + margin-top: 5px; } -div.admonition p.last, div.admonition div.last, div.admonition ul.last, div.admonition ol.last { - margin-bottom : 0px; +div.admonition p.last, +div.admonition div.last, +div.admonition ul.last, +div.admonition ol.last { + margin-bottom: 0px; } div.admonition dl.last > dd { - margin-bottom : 0; + margin-bottom: 0; } div.admonition dl.last > dd > :last-child { - margin-bottom : 0; + margin-bottom: 0; } tt.descclassname { - font-weight : normal; + font-weight: normal; } dt { - font-weight : bold; + font-weight: bold; } div.warning { - border : 1px solid #ff5050; + border: 1px solid #ff5050; } div.warning p.admonition-title { - border-bottom : 1px solid #ff5050; - background-color : #ff8080; + border-bottom: 1px solid #ff5050; + background-color: #ff8080; } - /* Tables */ -table.docutils th, table.docutils td { - border : 1px solid #C6C9CB !important; - padding : 7px 10px; +table.docutils th, +table.docutils td { + border: 1px solid #c6c9cb !important; + padding: 7px 10px; } table.docutils th { - background-color : #e1e5e7; + background-color: #e1e5e7; } table.docutils td[colspan] { - background-color : #ebeff1; - font-weight : bold; + background-color: #ebeff1; + font-weight: bold; } table.docutils td .last { - margin-bottom : 0; + margin-bottom: 0; } table.docutils tr.row-odd { - background-color : #f2f8ff; + background-color: #f2f8ff; } - - + table.field-list { - margin-top : 5px; + margin-top: 5px; } table.field-list tr.row-odd { - background-color : transparent; + background-color: transparent; } -table.field-list th, table.field-list td { - padding : 3px 8px 3px 5px; +table.field-list th, +table.field-list td { + padding: 3px 8px 3px 5px; } table.field-list th { - text-align : right; + text-align: right; } table.field-list td.field-body { - text-align : center; - min-width : 150px; - font-family : monospace; + text-align: center; + min-width: 150px; + font-family: monospace; } - /* Figures */ div.figure { - text-align : center; + text-align: center; } div.figure p.caption { - font-weight : bold; - font-size : 0.9em; + font-weight: bold; + font-size: 0.9em; } div.figure p.caption:before { - content : "Figure: " + content: "Figure: "; } div.figure img { - border: 1px solid #C6C9CB; - box-shadow: 1px 1px 1px #D8D8D8; - padding : 10px; + border: 1px solid #c6c9cb; + box-shadow: 1px 1px 1px #d8d8d8; + padding: 10px; } diff --git a/doc/source/building-and-running/considerations.rst b/doc/source/building-and-running/considerations.rst index 66359c89..24ecbd2f 100644 --- a/doc/source/building-and-running/considerations.rst +++ b/doc/source/building-and-running/considerations.rst @@ -7,9 +7,9 @@ Do I need NetCDF? ----------------- `NetCDF `_ is a data format (and associated software libraries) specifically designed for large-scale scientific data. It has two major benefits over raw binary data: - -1. It is machine-independent, so `endianness `_ is not an issue when moving datasets between machines -2. It is self-describing, so as well as containing raw data, NetCDF files also contain metadata describing the data (e.g. variable names, units, origin). Many tools are capable of exploiting this metadata to simplify processing. + +1. It is machine-independent, so `endianness `_ is not an issue when moving datasets between machines +2. It is self-describing, so as well as containing raw data, NetCDF files also contain metadata describing the data (e.g. variable names, units, origin). Many tools are capable of exploiting this metadata to simplify processing. JULES can be built with or without NetCDF, however *building JULES without NetCDF limits the functionality of JULES*. Without NetCDF, JULES will use a dummy NetCDF library which allows the program to build but provides no functionality. Any attempt to use NetCDF files as input with this option will result in a runtime error. All input files must be columnar ASCII, meaning that the user is restricted to running at a single point only. Output files will automatically use a columnar ASCII format with headers. File formats are discussed in more detail in :doc:`/input/overview`. @@ -19,17 +19,17 @@ Do I need parallel processing? .. note:: For running JULES at a single point, parallel processing provides no advantage. However, if JULES is already compiled with OpenMP or MPI enabled, it is still possible to run a single point by simply specifying the number of OpenMP threads and/or MPI tasks to be 1. - + JULES is capable of exploiting parallel processing techniques to reduce processing time for distributed/gridded simulations. There are two different methods JULES can use: - + OpenMP `OpenMP `_ is a form of compiler-assisted parallelisation that uses directives for shared-memory, loop-level parallelism across multiple cores on a machine (OpenMP is *not* capable of utilising a cluster of machines). - + This form of parallelism is not as effective as MPI, but may provide some speedup and does not require a specially compiled NetCDF library. - + MPI `MPI (Message Passing Interface) `_ is a standardised message passing interface. MPI coordinates the running of multiple 'tasks' in parallel, potentially on several machines (or nodes), and provides mechanisms for these tasks to communicate with each other. - + JULES takes advantage of the parallel I/O features available in `HDF5 `_ and `NetCDF4 `_, which enable multiple MPI tasks to read from and write to the same NetCDF file(s) at the same time. These features must be explicitly enabled when NetCDF is compiled (see :doc:`required-software`). It is also possible to use MPI and OpenMP together, where each MPI task has a number of OpenMP threads, however this is very advanced and beyond the scope of this document. diff --git a/doc/source/building-and-running/fcm.rst b/doc/source/building-and-running/fcm.rst index 0b6d9bd9..84327b92 100644 --- a/doc/source/building-and-running/fcm.rst +++ b/doc/source/building-and-running/fcm.rst @@ -12,7 +12,7 @@ Help pages for the FCM make command itself (rather than the configuration file) .. code-block:: bash fcm help make - + The FCM configuration file for building JULES is ``etc/fcm-make/make.cfg``. This file uses the environment variables below to determine the settings to use when compiling JULES. Running FCM make with this configuration file will create some files and directories in the specified build directory (see the ``-C`` option of ``fcm make``; defaults to the current working directory). The JULES executable will be produced in the specified build directory at ``build/bin/jules.exe``. @@ -25,10 +25,10 @@ Environment variables used when building JULES using FCM make ``JULES_PLATFORM`` Used to select settings for a pre-defined platform. The default values of other variables may depend on the choice of this setting; differences from the generic defaults are included in the descriptions below. - + .. note:: If you have many users using the same platform to run JULES, you may want to contribute a suitable platform configuration. - + +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Permitted value | Purpose | +============================+==============================================================================================================================================================+ @@ -69,12 +69,12 @@ Environment variables used when building JULES using FCM make | ``uoe-linux-gfortran`` | Use settings for the GFortran compiler on University of Exeter Linux system (SL7). | | | | +----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ - + ``JULES_REMOTE``, ``JULES_REMOTE_HOST``, ``JULES_REMOTE_PATH`` .. warning:: Advanced users only Used to determine whether the build will happen on a local or remote machine. - + +-----------------+----------------------------------------------------------------------------------+ | Permitted value | Purpose | +=================+==================================================================================+ @@ -88,10 +88,10 @@ Environment variables used when building JULES using FCM make | | The compilation can then be completed on the remote machine. See below for an | | | example. | +-----------------+----------------------------------------------------------------------------------+ - + ``JULES_COMPILER`` Used to select compiler specific settings. - + +-----------------+----------------------------------------------------------------------------------+ | Permitted value | Purpose | +=================+==================================================================================+ @@ -116,10 +116,10 @@ Environment variables used when building JULES using FCM make +-----------------+----------------------------------------------------------------------------------+ | ``fast`` | Compile JULES with additional settings for faster execution. | +-----------------+----------------------------------------------------------------------------------+ - + ``JULES_OMP`` Used to determine whether to build with OpenMP or not. - + +-----------------+----------------------------------------------------------------------------------+ | Permitted value | Purpose | +=================+==================================================================================+ @@ -130,7 +130,7 @@ Environment variables used when building JULES using FCM make ``JULES_MPI`` Used to determine whether to build with MPI enabled or not. - + +-----------------+----------------------------------------------------------------------------------+ | Permitted value | Purpose | +=================+==================================================================================+ @@ -141,7 +141,7 @@ Environment variables used when building JULES using FCM make ``JULES_NETCDF`` Indicates whether to use a dummy NetCDF library or a 'real' NetCDF library. - + +-----------------+----------------------------------------------------------------------------------+ | Permitted value | Purpose | +=================+==================================================================================+ @@ -157,15 +157,15 @@ Environment variables used when building JULES using FCM make ``JULES_NETCDF_PATH`` Path to NetCDF installation. - + This sets ``JULES_NETCDF_INC_PATH = $JULES_NETCDF_PATH/include`` and ``JULES_NETCDF_LIB_PATH = $JULES_NETCDF_PATH/lib``. These can be overridden by setting the variables directly. - + ``JULES_NETCDF_INC_PATH`` Path to NetCDF include directory (i.e. directory containing ``netcdf.mod``). - + ``JULES_NETCDF_LIB_PATH`` Path to NetCDF library directory (i.e. directory containing ``libnetcdff.a`` and ``libnetcdf.a``). - + .. note:: When compiled in parallel mode, NetCDF must be statically linked. This means the compiler must be able to find all required library and include files (i.e. for NetCDF, HDF5, curl and zlib) in ``JULES_NETCDF_INC_PATH``, ``JULES_NETCDF_LIB_PATH`` or the default search path. @@ -200,7 +200,7 @@ To create a fast JULES executable with NetCDF using the Intel compiler: $ export JULES_NETCDF=netcdf $ export JULES_NETCDF_PATH=/path/to/netcdf # Replace this with the correct path $ fcm make -j 2 -f etc/fcm-make/make.cfg --new - + To create a fast JULES executable with NetCDF using the GFortran compiler on a Met Office Linux system (making use of the platform setting): .. code-block:: bash @@ -209,7 +209,7 @@ To create a fast JULES executable with NetCDF using the GFortran compiler on a M $ export JULES_BUILD=fast $ export JULES_NETCDF=netcdf # Note that we don't need to specify paths $ fcm make -j 2 -f etc/fcm-make/make.cfg --new - + To create a normal JULES executable with NetCDF and OpenMP using the Intel compiler on a remote machine: .. code-block:: bash @@ -229,14 +229,14 @@ To create a normal JULES executable with NetCDF and OpenMP using the Intel compi To create a normal JULES executable with MPI enabled, using the Intel compiler with array bounds checking turned on: .. code-block:: bash - + $ export JULES_COMPILER=intel $ export JULES_MPI=mpi $ export JULES_NETCDF=netcdf # We have to use NetCDF for distributed simulations $ export JULES_NETCDF_PATH=/path/to/parallel/netcdf # NetCDF must be compiled with parallel I/O enabled $ export JULES_FFLAGS_EXTRA="-check bounds" # Must be quoted because of the space $ fcm make -j 2 -f etc/fcm-make/make.cfg --new - + Tips for effective use of FCM make ---------------------------------- @@ -244,7 +244,7 @@ Tips for effective use of FCM make * To check the current values of the environment variables JULES will use to build, use the command ``env | grep JULES`` * If you always use the same compilation options for JULES, consider adding the export lines to the ``.profile`` file in your ``$HOME`` directory. Commands in the ``.profile`` file are automatically executed in any shell that you open, so defining environment variables there ensures your build environment remains consistent across shells and restarts of your computer. The definitions can still be overridden on the command line if required. - + .. _JULES development virtual machine: https://code.metoffice.gov.uk/trac/jules/wiki/JULESVirtualMachine .. _GNU Fortran compiler: https://www.gnu.org/software/gcc/fortran/ diff --git a/doc/source/building-and-running/intro.rst b/doc/source/building-and-running/intro.rst index 4ab3fc43..77a63a90 100644 --- a/doc/source/building-and-running/intro.rst +++ b/doc/source/building-and-running/intro.rst @@ -2,13 +2,11 @@ Building and running JULES ========================== - This section details the options available for compiling and running JULES. - .. toctree:: :maxdepth: 2 - + considerations required-software fcm diff --git a/doc/source/building-and-running/required-software.rst b/doc/source/building-and-running/required-software.rst index c9c6715d..480f35c6 100644 --- a/doc/source/building-and-running/required-software.rst +++ b/doc/source/building-and-running/required-software.rst @@ -7,14 +7,13 @@ To be able to automatically upgrade namelists between JULES versions or use a GU All of this software is freely available: -* GFortran, the GNU GCC Fortran compiler - https://www.gnu.org/software/gcc/fortran -* FCM - http://metomi.github.io/fcm/doc -* Rose - http://metomi.github.io/rose/doc/html/index.html -* NetCDF libraries - http://www.unidata.ucar.edu/software/netcdf +* GFortran, the GNU GCC Fortran compiler - https://www.gnu.org/software/gcc/fortran +* FCM - http://metomi.github.io/fcm/doc +* Rose - http://metomi.github.io/rose/doc/html/index.html +* NetCDF libraries - http://www.unidata.ucar.edu/software/netcdf JULES has only been tested on Linux but, given a suitable Fortran compiler, should run on any Unix-like system with minimal changes. The recommended way to attempt to run JULES on Windows is via the Linux compatability layer `Cygwin `_, although this is untested. - Building JULES with NetCDF -------------------------- diff --git a/doc/source/building-and-running/rose.rst b/doc/source/building-and-running/rose.rst index ec4bb132..347da5b1 100644 --- a/doc/source/building-and-running/rose.rst +++ b/doc/source/building-and-running/rose.rst @@ -8,14 +8,14 @@ Automatic upgrading and GUI using Rose .. note:: This section assumes `Rose is installed `_. - + We will not be using Rose Bush or Rosie, so those components need not be installed. - + It is not necessary to install Cylc, but some functionality will not be available. This will be noted as we go. JULES uses Rose primarily to provide a graphical interface for configuring and running JULES, but also to allow automatic upgrading of JULES runs from one version to the next. -A Rose suite for JULES will normally contain two applications - an ``fcm_make`` application for building JULES and a ``jules`` application for configuring the namelists and running JULES. +A Rose suite for JULES will normally contain two applications - an ``fcm_make`` application for building JULES and a ``jules`` application for configuring the namelists and running JULES. Creating a Rose suite from existing namelists @@ -28,7 +28,7 @@ To convert vn3.4 namelists to a vn4.7 Rose suite, run the following command in t .. code-block:: bash create_rose_app vn3.4 vn4.7 namelist_path suite_name jules_dir - + Where ``jules_dir`` is the path to the root directory of the most recent JULES code release on your machine. The ``namelist_path`` can be the full or a relative path. @@ -49,17 +49,17 @@ In order to use Rose to upgrade existing namelists from vn3.4 to vn4.0, just exe # Creates a Rose suite at rose-suite $JULES_ROOT/bin/create_rose_app vn3.4 vn4.0 - + # Remove the current namelists rm -rf *.nml - + # Use Rose to generate the new namelists rose app-run -i -C rose-suite/app/jules - + # Remove the Rose suite and other generated files rm -rf rose-suite .rose-config_processors-file.db rose-app-run.conf - - + + Upgrading an existing JULES Rose suite -------------------------------------- @@ -72,7 +72,7 @@ Upgrading an existing JULES Rose suite is even more simple than upgrading the na rose app-upgrade -M $JULES_ROOT/rose-meta -C /path/to/rose/suite/app/fcm_make --all-versions && rose macro --fix -C app/fcm_make - + To then upgrade to one of those versions, the command is: .. code-block:: bash @@ -83,7 +83,7 @@ To then upgrade to one of those versions, the command is: rose app-upgrade -M $JULES_ROOT/rose-meta -C /path/to/rose/suite/app/fcm_make && rose macro --fix -C app/fcm_make - + Configuring JULES with a graphical interface -------------------------------------------- @@ -95,10 +95,10 @@ To launch the graphical editor, the following command is used: # To edit the whole suite, including build configuration rose config-edit -M $JULES_ROOT/rose-meta -C /path/to/rose/suite & - + # To edit just the namelists rose config-edit -M $JULES_ROOT/rose-meta -C /path/to/rose/suite/app/jules & - + where ``$JULES_ROOT`` is the root directory of your JULES installation. For more information on using the config editor, see `the Rose documentation `_ Clicking on a variable name in the editor opens the corresponding page in this documentation. @@ -117,8 +117,8 @@ To generate namelists in the current directory from a Rose suite at ``/path/to/r .. code-block:: bash rose app-run -i -C /path/to/rose/suite/app/jules - - + + With Cylc ^^^^^^^^^ @@ -129,5 +129,5 @@ Once a JULES Rose suite has been suitably configured using the graphical editor, .. code-block:: bash rose suite-run -C /path/to/rose/suite - + This will set the suite running, and will launch the `Cylc `_ GUI to allow you to see the status of your suite as it runs. The GUI also allows you to view log files etc. - these can be useful when a job fails! diff --git a/doc/source/building-and-running/running-jules.rst b/doc/source/building-and-running/running-jules.rst index bae66258..14c68719 100644 --- a/doc/source/building-and-running/running-jules.rst +++ b/doc/source/building-and-running/running-jules.rst @@ -8,22 +8,22 @@ Once a :doc:`JULES executable is compiled ` and the :doc:`namelists `__ or the -'Example configurations' row of the table `here `__. +If you are using a version of JULES since vn5.0, please see the list of standard +jobs in the table given `here `__ +or the 'Example configurations' row of the table `here `__. For earlier versions, please see chapter 8 of the appropriate `JULES User Guide `__. diff --git a/doc/source/index.rst b/doc/source/index.rst index 6709c715..b928a688 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -8,9 +8,19 @@ Joint UK Land Environment Simulator (JULES) User Guide ====================================================== -The Joint UK Land Environment Simulator (JULES) is a computer model that simulates many soil and vegetation processes. This guide primarily describes the format of the input and output files, and does not include detailed descriptions of the science and representation of the processes in the model. - -The first version of JULES was based on the Met Office Surface Exchange System (MOSES), the land surface model used in the `Unified Model `_ (UM) of the `UK Met Office `_. After that initial split, the MOSES and JULES code bases evolved separately, but with JULES v2.1 these differences were reconciled with the UM. As of JULES v3.1, a single code repository is used for both standalone JULES and JULES in the UM. +The Joint UK Land Environment Simulator (JULES) is a computer model that +simulates many soil and vegetation processes. This guide primarily describes the +format of the input and output files, and does not include detailed descriptions +of the science and representation of the processes in the model. + +The first version of JULES was based on the Met Office Surface Exchange System (MOSES), +the land surface model used in the +`Unified Model `_ (UM) +of the `UK Met Office `_. +After that initial split, the MOSES and JULES code bases evolved separately, +but with JULES v2.1 these differences were reconciled with the UM. +As of JULES v3.1, a single code repository is used for both +standalone JULES and JULES in the UM. Further information can be found on the JULES website: http://jules.jchmr.org/. @@ -18,7 +28,7 @@ Further information can be found on the JULES website: http://jules.jchmr.org/. .. toctree:: :maxdepth: 1 :numbered: - + release_notes/contents overview/intro building-and-running/intro diff --git a/doc/source/input/ascii.rst b/doc/source/input/ascii.rst index 2747b358..19a90508 100644 --- a/doc/source/input/ascii.rst +++ b/doc/source/input/ascii.rst @@ -1,7 +1,7 @@ ASCII files =========== -JULES only supports the use of ASCII files for data at a single location. In this case, the input grid can be specified either as a 1D grid with length 1 or as a 2D grid of size 1 x 1. The data should be laid out in columns with one timestep of data per row (with time increasing with the number of rows). For variables with additional 'levels' dimensions (e.g. soil layers), the values for each level should be in consecutive columns. +JULES only supports the use of ASCII files for data at a single location. In this case, the input grid can be specified either as a 1D grid with length 1 or as a 2D grid of size 1 x 1. The data should be laid out in columns with one timestep of data per row (with time increasing with the number of rows). For variables with additional 'levels' dimensions (e.g. soil layers), the values for each level should be in consecutive columns. .. note:: Variables should be given to JULES in the order they appear in the file, and there should be no unused variables in between. This may mean that some datasets may require pre-processing for use with JULES, even if they are already columnar. @@ -47,6 +47,6 @@ Time varying data with an additional dimension 0.0 0.0 0.2 0.0 0.0 0.0 0.0 0.6 0.0 0.0 0.0 0.0 0.2 0.0 0.0 0.0 0.0 0.6 0.0 0.0 0.0 0.0 0.2 0.0 0.0 0.0 0.0 0.7 0.0 0.0 - # ... + # ... These variables have one value for each plant functional type (see :doc:`/overview/intro`). For each variable, the values for each pft are in consecutive columns. Each row is one timestep of data. diff --git a/doc/source/input/file-name-templating.rst b/doc/source/input/file-name-templating.rst index ca09b57e..14a6085c 100644 --- a/doc/source/input/file-name-templating.rst +++ b/doc/source/input/file-name-templating.rst @@ -11,27 +11,27 @@ Time templating If any of the time templating substitution strings are present in a file name, then JULES assumes time-templating is to be used. The valid substitution strings for time templating are: -+-----------------------+------------------------------------------------------------------------------------------------+ -| Substitution string | Replaced with | -+=======================+================================================================================================+ -| ``%y4`` | 4-digit year | -+-----------------------+------------------------------------------------------------------------------------------------+ -| ``%y2`` | 2-digit year | -+-----------------------+------------------------------------------------------------------------------------------------+ -| ``%m2`` | 2-digit month | -+-----------------------+------------------------------------------------------------------------------------------------+ -| ``%m1`` | 1- or 2-digit month | -+-----------------------+------------------------------------------------------------------------------------------------+ -| ``%mc`` | 3-character month abbreviation | -+-----------------------+------------------------------------------------------------------------------------------------+ -| ``%d2`` | 2-digit day of month | -+-----------------------+------------------------------------------------------------------------------------------------+ ++-----------------------+----------------------------------+ +| Substitution string | Replaced with | ++=======================+==================================+ +| ``%y4`` | 4-digit year | ++-----------------------+----------------------------------+ +| ``%y2`` | 2-digit year | ++-----------------------+----------------------------------+ +| ``%m2`` | 2-digit month | ++-----------------------+----------------------------------+ +| ``%m1`` | 1- or 2-digit month | ++-----------------------+----------------------------------+ +| ``%mc`` | 3-character month abbreviation | ++-----------------------+----------------------------------+ +| ``%d2`` | 2-digit day of month | ++-----------------------+----------------------------------+ JULES will automatically detect the period (or frequency) of files based on the specific substitution strings in the following manner: .. figure:: time_templating_flow_diagram.png :alt: Time templating flow diagram - + Flow diagram showing detection of file period from time templated string This means that monthly files must also have a year substitution string present, and daily files must have both month and year substitution strings present. Only yearly, monthly and daily files are allowed with time templating, with each file containing a single period (year, month or day respectively) of data. For yearly files, the first data in each file must apply from 00:00:00 on 1st January for each year. For monthly files, the first data in the file must apply from 00:00:00 on the 1st of the month. For daily files, the first data in the file must apply from 00:00:00 on the given day. Other configurations can be specified using a list of files with their respective start times. @@ -53,33 +53,33 @@ Data is in monthly files with all related variables in the same file. Template: -.. code-block:: none +.. code-block:: text /data/met_data_%y4%m2.nc Example filenames: -.. code-block:: none +.. code-block:: text /data/met_data_199001.nc /data/met_data_199002.nc ... /data/met_data_200410.nc - + Variable name templating only ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Ancillary (non-time-varying) data with each variable in similarly named but separate files. Template: - -.. code-block:: none + +.. code-block:: text /ancil/soil_%vv.nc - + Example filenames: - -.. code-block:: none + +.. code-block:: text /data/soil_satcon.nc /data/soil_sathh.nc @@ -91,32 +91,32 @@ Data is in monthly files with each variable in similarly named but separate file Template: -.. code-block:: none +.. code-block:: text /data/%vv_%y4%mc.nc - + Example filenames: -.. code-block:: none +.. code-block:: text /data/Rain_1990jan.nc /data/Wind_1990jan.nc ... /data/Rain_2000oct.nc /data/Wind_2000oct.nc - + Variable name templating with a list of files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Data in 6-monthly files with each variable in similarly named but separate files. - + Since the time templating cannot handle 6-monthly files, the files and their start times must be specified as a list. However, variable name templating can still be used. - + Also note that it is possible to use a substitution string more than once in a template. Template list: -.. code-block:: none +.. code-block:: text ./%vv/met_%vv_199001.nc ./%vv/met_%vv_199007.nc @@ -125,7 +125,7 @@ Template list: Example filenames: -.. code-block:: none +.. code-block:: text ./Rain/met_Rain_199001.nc ./Wind/met_Wind_199001.nc diff --git a/doc/source/input/netcdf.rst b/doc/source/input/netcdf.rst index 7e4d5241..90cd662f 100644 --- a/doc/source/input/netcdf.rst +++ b/doc/source/input/netcdf.rst @@ -6,4 +6,4 @@ For gridded data, NetCDF is the only supported format. Although ASCII files can * All input files use the same grid. * All input files use the same dimension names (for grid dimensions, any additional dimensions and the time dimension). * The dimensions for each variable appear in the correct order - ``(points, z1, z2, ..., t)`` for a 1D grid and ``(x, y, z1, z2, ..., t)`` for a 2D grid, where the ``z1, z2, ...`` (levels) and ``t`` (time) dimensions are only present when the variable and context in which the variable is being used require them. -* If using NetCDF for data at a single location, the grid dimensions are still expected to exist with size 1. \ No newline at end of file +* If using NetCDF for data at a single location, the grid dimensions are still expected to exist with size 1. diff --git a/doc/source/input/overview.rst b/doc/source/input/overview.rst index 4a03f5a0..3202876d 100644 --- a/doc/source/input/overview.rst +++ b/doc/source/input/overview.rst @@ -1,10 +1,8 @@ Input files for JULES ===================== - The recommended file format for use with JULES is NetCDF, although an ASCII format is also supported for data at a single location only. NetCDF is recommended since in this format, the metadata are provided in a standardised manner that many other tools and applications can interpret. The file handling code of JULES is written in a modular way that aims to make it easy for the user to add support for other file formats if they desire. Any user that does this is strongly encouraged to contribute their code back to the community. - .. toctree:: principles ascii diff --git a/doc/source/input/principles.rst b/doc/source/input/principles.rst index 121869de..90878d07 100644 --- a/doc/source/input/principles.rst +++ b/doc/source/input/principles.rst @@ -20,4 +20,4 @@ ASCII files ``.asc``, ``.txt`` and ``.dat`` NetCDF files - ``.nc`` and ``.cdf`` \ No newline at end of file + ``.nc`` and ``.cdf`` diff --git a/doc/source/input/temporal-interpolation.rst b/doc/source/input/temporal-interpolation.rst index f838c809..f04729ea 100644 --- a/doc/source/input/temporal-interpolation.rst +++ b/doc/source/input/temporal-interpolation.rst @@ -14,23 +14,23 @@ When JULES needs to know what type of interpolation to use for a variable, the f ``i`` Linear interpolation from the data timestep to the model timestep. - + For instantaneous data (e.g. air temperature, surface pressure), this is almost always the flag that should be used. - + ``nb``, ``nc`` and ``nf`` - Values will be held constant with time for all model timesteps associated with a particular data timestep. - + Values will be held constant with time for all model timesteps associated with a particular data timestep. + One of these flags should be used for flux variables that are *discontinuous* by nature, e.g. precipitation. - + ``nb`` should be used if the dataset uses backwards average values, ``nf`` should be used if the data set uses forwards average values and ``nc`` should be used if the dataset uses centred average values (this is quite rare). - + ``b``, ``c`` and ``f`` Data is interpolated using a simplified version of the Sheng and Zwiers (1998) [#]_ method that conserves the period means of the data. - + One of these flags should be used for flux variables that are *continuous* in nature, e.g. radiation. In order to ensure conservation of the average, these flags should be used only if the data period is an even multiple of the model timestep (i.e., if ``data_period = 2 * n * timestep_len; n = 1, 2, 3, ...``). The curve-fitting process tends to produce occasional values near turning points that fall outside the range of the input values. - + Similar to above, ``b`` should be used if the dataset uses backwards average values, ``f`` should be used if the data set uses forwards average values and ``c`` should be used if the dataset uses centred average values. @@ -54,7 +54,7 @@ Also, note that for centred data (flags ``c`` and ``nc``) the time of the data s .. figure:: interp_examples.png :alt: Examples of JULES interpolation modes - + Examples of data interpolated with ``i``, ``nb``, ``nf``, ``b`` and ``f``, plotted against the data they are derived from diff --git a/doc/source/namelists/ancillaries.nml.rst b/doc/source/namelists/ancillaries.nml.rst index 99502246..2b9bd9b2 100644 --- a/doc/source/namelists/ancillaries.nml.rst +++ b/doc/source/namelists/ancillaries.nml.rst @@ -1,7 +1,6 @@ ``ancillaries.nml`` =================== - This file sets up spatially varying ancillary values. It contains the following namelists: :nml:lst:`JULES_FRAC`, :nml:lst:`JULES_VEGETATION_PROPS`, :nml:lst:`JULES_SOIL_PROPS`, :nml:lst:`JULES_TOP`, :nml:lst:`JULES_PDM`, :nml:lst:`JULES_AGRIC`, :nml:lst:`JULES_CROP_PROPS`, :nml:lst:`JULES_IRRIG_PROPS`, :nml:lst:`JULES_RIVERS_PROPS`, :nml:lst:`JULES_WATER_RESOURCES_PROPS`, :nml:lst:`URBAN_PROPERTIES` , :nml:lst:`JULES_CO2` and :nml:lst:`JULES_FLAKE`. Data associated with each of these namelists can optionally be read from the dump file (if present) by setting ``read_from_dump`` to true. This functionality provides closer alignment with UM functionality and can help ensure that the correct ancillary data remain associated with the model state. @@ -30,7 +29,6 @@ If using either URBAN-2T or MORUSES then the total *urban* fraction can be speci FALSE Use the other namelist members to determine how to populate variables. - .. nml:member:: file :type: character @@ -38,7 +36,6 @@ If using either URBAN-2T or MORUSES then the total *urban* fraction can be speci The name of the file to read surface type fractional coverage data from. - .. nml:member:: frac_name :type: character @@ -50,8 +47,6 @@ If using either URBAN-2T or MORUSES then the total *urban* fraction can be speci This is only used for NetCDF files. For ASCII files, the surface type fractional coverage data is expected to be the first (ideally only) variable in the file. - - .. note:: The open water fraction of this array (given by :nml:mem:`JULES_SURFACE_TYPES::lake`) should contain permanent water, and wetland extents that are not being otherwise simulated. If groundwater inundation is being simulated (i.e. TOPMODEL is active :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE and therefore fsat is being calculated) then all groundwater-maintained wetlands must be excluded from :nml:mem:`JULES_FRAC::frac_name`. @@ -61,7 +56,6 @@ If using either URBAN-2T or MORUSES then the total *urban* fraction can be speci In the file, the variable must have a single levels dimension of size ``ntype`` called :nml:mem:`JULES_INPUT_GRID::type_dim_name`, and should not have a time dimension. - ``JULES_VEGETATION_PROPS`` namelist members ------------------------------------------- @@ -203,8 +197,6 @@ List of vegetation parameters +-----------------+--------------------------------------------------------------------------------------+ - - ``JULES_SOIL_PROPS`` namelist members ------------------------------------- @@ -416,7 +408,7 @@ In all cases, the variables must have no time dimension. .. nml:namelist :: JULES_TOP -This namelist reads spatially varying parameter values for the TOPMODEL-type parameterisation of runoff. The values are only used if :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE. The description below is very brief. For further details, see the references under :nml:mem:`JULES_HYDROLOGY::l_top`. +This namelist reads spatially varying parameter values for the TOPMODEL-type parametrisation of runoff. The values are only used if :nml:mem:`JULES_HYDROLOGY::l_top` = TRUE. The description below is very brief. For further details, see the references under :nml:mem:`JULES_HYDROLOGY::l_top`. .. nml:member:: read_from_dump @@ -562,7 +554,7 @@ All of the TOPMODEL variables listed below are expected to have no levels dimens .. nml:namelist :: JULES_PDM -This namelist reads spatially varying parameter values for the PDM-type parameterisation of runoff. The values are only used if :nml:mem:`JULES_HYDROLOGY::l_pdm` = TRUE. The description below is very brief. For further details, see the references under :nml:mem:`JULES_HYDROLOGY::l_pdm`. +This namelist reads spatially varying parameter values for the PDM-type parametrisation of runoff. The values are only used if :nml:mem:`JULES_HYDROLOGY::l_pdm` = TRUE. The description below is very brief. For further details, see the references under :nml:mem:`JULES_HYDROLOGY::l_pdm`. .. nml:member:: read_list @@ -1023,7 +1015,7 @@ All of the crop variables listed below are expected to have a single levels dime References: * Osborne et al, `JULES-crop: a parametrisation of crops in the Joint UK Land Environment Simulator `_, Geosci. Model Dev., 8, 1139-1155, 2015. - * Mathison et al, 'Developing a sequential cropping capability in the JULESvn5.2 land–surface model', Geosci. Model Dev. Discuss., https://doi.org/10.5194/gmd-2019-85, in review, 2019 + * Mathison et al, 'Developing a sequential cropping capability in the JULESvn5.2 land-surface model', Geosci. Model Dev. Discuss., https://doi.org/10.5194/gmd-2019-85, in review, 2019 ``JULES_IRRIG_PROPS`` namelist members @@ -1096,7 +1088,6 @@ This namelist specifies the options available for initialising irrigated fractio The constant irrigated fraction to be applied to specific surface tiles given in :nml:mem:`JULES_IRRIG::irrigtiles`. - ``JULES_RIVERS_PROPS`` namelist members --------------------------------------- @@ -1127,10 +1118,8 @@ This namelist specifies how spatially varying river routing properties including The most satisfactory situation is one in which the areas covered by land and river gridboxes are identical (though the resolutions can differ). In that case all the runoff that is generated on the land is correctly captured by the river network, and each river length has a well-defined input of local runoff. However there are situations in which the user might be prepared to allow other configurations - e.g. if studying a particular catchment, land in headwaters of surrounding catchments might not be covered by the river ancillary. - .. nml:group:: Members used to define the river routing input grid - .. nml:member:: coordinate_file :type: character @@ -1138,7 +1127,6 @@ This namelist specifies how spatially varying river routing properties including The file from which to read coordinate information for the river routing input grid. This is only used when :nml:mem:`file` includes :doc:`variable-name templating ` or when :nml:mem:`read_list` = TRUE, i.e. it is only used when ancillary variables will come from multiple files, in which case this variable is used to provide clarity as to where the coordinates are read from. - .. nml:member:: x_dim_name :type: character @@ -1149,7 +1137,6 @@ This namelist specifies how spatially varying river routing properties including .. note:: For ASCII files, this can be anything. For NetCDF files, it should be the name of the dimension in :nml:mem:`file` (if that does not include :doc:`variable-name templating `) or in :nml:mem:`coordinate_file` (if :nml:mem:`file` includes templating). .. note:: Values for the coordinates along the x dimension of the river routing input grid will be read from the input file to define the river grid, and it is assumed that the file contains a variable with the same name as the dimension (x_dim_name). - .. nml:member:: y_dim_name :type: character @@ -1543,13 +1530,13 @@ Since both grids are 1\ |deg| x 1\ |deg|, we define the 2D regular lat-lon grid .. |deg| unicode:: U+00B0 - +.. |iacute| replace:: í .. seealso:: References: - * Appx B of Lewis HW, Castillo Sanchez JM, Graham J, Saulter A, Bornemann J, Arnold A, Fallmann J, Harris C, Pearson D, Ramsdale S, Martínez de la Torre A, Bricheno L, Blyth E, Bell VA, Davies H, Marthews TR, O'Neill C, Rumbold H, O'Dea E, Brereton A, Guihou K, Hines A, Butenschon M, Dadson SJ, Palmer T, Holt J, Reynard N, Best M, Edwards J & Siddorn J (2018). The UKC2 regional coupled environmental prediction system. Geoscientific Model Development 11:1-42. + * Appx B of Lewis HW, Castillo Sanchez JM, Graham J, Saulter A, Bornemann J, Arnold A, Fallmann J, Harris C, Pearson D, Ramsdale S, Mart|iacute|nez de la Torre A, Bricheno L, Blyth E, Bell VA, Davies H, Marthews TR, O'Neill C, Rumbold H, O'Dea E, Brereton A, Guihou K, Hines A, Butenschon M, Dadson SJ, Palmer T, Holt J, Reynard N, Best M, Edwards J & Siddorn J (2018). The UKC2 regional coupled environmental prediction system. Geoscientific Model Development 11:1-42. * Bell, V.A. et al. (2007) Development of a high resolution grid-based river flow model for use with regional climate model output. Hydrology and Earth System Sciences. 11 532-549 * Oki, T., et al (1999) Assessment of annual runoff from land surface models using Total Runoff Integrating Pathways (TRIP). Journal of the Meteorological Society of Japan. 77 235-255 @@ -1680,16 +1667,16 @@ The following table summarises ancillary fields for the water resources code, sp .. tabularcolumns:: |p{3cm}|L| -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| Name | Description | -+============================+===========================================================================================================+ -| ``conv_loss_frac`` | Fraction of abstracted water that is lost during conveyance from source to user. | -| | | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``sfc_water_frac`` | Target for the fraction of demand that will be met from surface water (rather than groundwater). | -| | This is only used if :nml:mem:`JULES_WATER_RESOURCES::partition_method` = 1. | -| | | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ ++----------------------+--------------------------------------------------------------------------------------------------+ +| Name | Description | ++======================+==================================================================================================+ +| ``conv_loss_frac`` | Fraction of abstracted water that is lost during conveyance from source to user. | +| | | ++----------------------+--------------------------------------------------------------------------------------------------+ +| ``sfc_water_frac`` | Target for the fraction of demand that will be met from surface water (rather than groundwater). | +| | This is only used if :nml:mem:`JULES_WATER_RESOURCES::partition_method` = 1. | +| | | ++----------------------+--------------------------------------------------------------------------------------------------+ @@ -1808,32 +1795,31 @@ List of urban properties All of the urban property variables listed below are expected to have no levels dimensions and no time dimension. -+---------------+----------------------------------+-------------------------------------------------------------------------------------+ -| Variable name | Description [#]_ | Notes | -+===============+==================================+=====================================================================================+ -| ``wrr`` | Repeating width ratio (or canyon | If :nml:mem:`JULES_URBAN::l_urban_empirical` = TRUE | -| | fraction, W/R) | then this is updated with calculated values. | -+---------------+----------------------------------+-------------------------------------------------------------------------------------+ -| **The following apply to MORUSES only** | -+---------------+----------------------------------+-------------------------------------------------------------------------------------+ -| ``hwr`` | Height-to-width ratio (H/W) | See for ``wrr`` above. | -+---------------+----------------------------------+-------------------------------------------------------------------------------------+ -| ``hgt`` | Building height (H) | See for ``wrr`` above. | -+---------------+----------------------------------+-------------------------------------------------------------------------------------+ -| ``ztm`` | Effective roughness length of | If :nml:mem:`JULES_URBAN::l_moruses_macdonald` = TRUE | -| | urban areas | then this is updated with calculated values. | -+---------------+----------------------------------+-------------------------------------------------------------------------------------+ -| ``disp`` | Displacement height | See for ``ztm`` above. | -+---------------+----------------------------------+-------------------------------------------------------------------------------------+ -| ``albwl`` | Wall albedo | Data only used if :nml:mem:`JULES_URBAN::l_moruses_albedo` = TRUE. | -+---------------+----------------------------------+-------------------------------------------------------------------------------------+ -| ``albrd`` | Road albedo | See for ``albwl`` above. | -+---------------+----------------------------------+-------------------------------------------------------------------------------------+ -| ``emisw`` | Wall emissivity | Data only used if :nml:mem:`JULES_URBAN::l_moruses_emissivity` = TRUE. | -+---------------+----------------------------------+-------------------------------------------------------------------------------------+ -| ``emisr`` | Road emissivity | See for ``emisw`` above. | -+---------------+----------------------------------+-------------------------------------------------------------------------------------+ - ++---------------+----------------------------------+------------------------------------------------------------------------+ +| Variable name | Description [#]_ | Notes | ++===============+==================================+========================================================================+ +| ``wrr`` | Repeating width ratio (or canyon | If :nml:mem:`JULES_URBAN::l_urban_empirical` = TRUE | +| | fraction, W/R) | then this is updated with calculated values. | ++---------------+----------------------------------+------------------------------------------------------------------------+ +| **The following apply to MORUSES only** | ++---------------+----------------------------------+------------------------------------------------------------------------+ +| ``hwr`` | Height-to-width ratio (H/W) | See for ``wrr`` above. | ++---------------+----------------------------------+------------------------------------------------------------------------+ +| ``hgt`` | Building height (H) | See for ``wrr`` above. | ++---------------+----------------------------------+------------------------------------------------------------------------+ +| ``ztm`` | Effective roughness length of | If :nml:mem:`JULES_URBAN::l_moruses_macdonald` = TRUE | +| | urban areas | then this is updated with calculated values. | ++---------------+----------------------------------+------------------------------------------------------------------------+ +| ``disp`` | Displacement height | See for ``ztm`` above. | ++---------------+----------------------------------+------------------------------------------------------------------------+ +| ``albwl`` | Wall albedo | Data only used if :nml:mem:`JULES_URBAN::l_moruses_albedo` = TRUE. | ++---------------+----------------------------------+------------------------------------------------------------------------+ +| ``albrd`` | Road albedo | See for ``albwl`` above. | ++---------------+----------------------------------+------------------------------------------------------------------------+ +| ``emisw`` | Wall emissivity | Data only used if :nml:mem:`JULES_URBAN::l_moruses_emissivity` = TRUE. | ++---------------+----------------------------------+------------------------------------------------------------------------+ +| ``emisr`` | Road emissivity | See for ``emisw`` above. | ++---------------+----------------------------------+------------------------------------------------------------------------+ .. rubric:: Footnotes diff --git a/doc/source/namelists/cable_pftparm.nml.rst b/doc/source/namelists/cable_pftparm.nml.rst index cb31433e..249a99a6 100644 --- a/doc/source/namelists/cable_pftparm.nml.rst +++ b/doc/source/namelists/cable_pftparm.nml.rst @@ -4,7 +4,7 @@ This file sets the time and space-invariant parameters for plant functional types for the CABLE land surface model. It contains one namelist called :nml:lst:`CABLE_PFTPARM`. ``CABLE_PFTPARM`` namelist members ------------------------------------ +---------------------------------- .. nml:namelist:: CABLE_PFTPARM diff --git a/doc/source/namelists/cable_prognostics.nml.rst b/doc/source/namelists/cable_prognostics.nml.rst index c3deb811..3e28f12e 100644 --- a/doc/source/namelists/cable_prognostics.nml.rst +++ b/doc/source/namelists/cable_prognostics.nml.rst @@ -123,4 +123,4 @@ Values are set for each tile of each grid point and for each layer of soil or sn | ``OneLyrSnowDensity_CABLE`` | Snow density when all snow treated as one layer. (kg m\ :sup:`-3`) | +-------------------------------+-------------------------------------------------------------------------------+ | ``ThreeLayerSnowFlag_CABLE`` | Flag for 3 layer snow pack (0 - false, 1 - true) | -+-------------------------------+-------------------------------------------------------------------------------+ \ No newline at end of file ++-------------------------------+-------------------------------------------------------------------------------+ diff --git a/doc/source/namelists/cable_soilparm.nml.rst b/doc/source/namelists/cable_soilparm.nml.rst index 017b7f42..164a0172 100644 --- a/doc/source/namelists/cable_soilparm.nml.rst +++ b/doc/source/namelists/cable_soilparm.nml.rst @@ -1,7 +1,6 @@ ``cable_soilparm.nml`` ============================ - This file contains a namelist called :nml:lst:`CABLE_SOILPARM` that sets time-invariant parameters for different soil types for the CABLE land surface model. ``CABLE_SOILPARM`` namelist members @@ -99,6 +98,3 @@ The number of soil types is stored in the `n_soiltypes` parameter and for the cu :default: MDI Soil specific heat capacity (J kg\ :sup:`-1` K\ :sup:`-1`). - - - diff --git a/doc/source/namelists/cable_surface_types.nml.rst b/doc/source/namelists/cable_surface_types.nml.rst index 5fc9edeb..6f0cfa8d 100644 --- a/doc/source/namelists/cable_surface_types.nml.rst +++ b/doc/source/namelists/cable_surface_types.nml.rst @@ -1,7 +1,6 @@ ``cable_surface_types.nml`` ================================= - This file configures the surface types used by CABLE. It contains one namelist called :nml:lst:`CABLE_SURFACE_TYPES`. @@ -18,8 +17,8 @@ This file configures the surface types used by CABLE. It contains one namelist c :default: -32768 The number of plant functional types to be modelled. - - + + .. nml:member:: nnvg_cable :type: integer @@ -27,13 +26,13 @@ This file configures the surface types used by CABLE. It contains one namelist c :default: -32768 The number of non-plant surface types to be modelled. - - + + .. note:: The total number of surface types to be modelled is called ``ntype_cable``, and is given by ``ntype_cable = npft_cable + nnvg_cable``. - + In the standard setup, CABLE models 13 vegetation types and 4 non-vegetation types (``npft_cable = 13``, ``nnvg_cable = 4``). However, the model domain need not contain all 13 types, e.g. the domain could consist of a single point with 100% grass. The amount of each type in the domain is normally set in :nml:lst:`JULES_FRAC`. - + .. nml:member:: urban_drive @@ -70,4 +69,3 @@ This file configures the surface types used by CABLE. It contains one namelist c Index of the ice surface type. A negative value indicates no ice surface type. - diff --git a/doc/source/namelists/contents.rst b/doc/source/namelists/contents.rst index bf038a3d..5ae8de77 100644 --- a/doc/source/namelists/contents.rst +++ b/doc/source/namelists/contents.rst @@ -2,7 +2,8 @@ The JULES namelist files ======================== -Each run of JULES is controlled by a number of files containing Fortran namelists. These files specify details including: +Each run of JULES is controlled by a number of files containing Fortran +namelists. These files specify details including: * Switches to allow different model configurations to be selected at run-time. * Start and end times for the run. @@ -11,8 +12,9 @@ Each run of JULES is controlled by a number of files containing Fortran namelist * Values for various parameters. * The required output. -These files have specific names, and JULES expects all these files to exist for every run (even when their contents are not required). JULES also expects that the namelists within each file appear in the order given below. - +These files have specific names, and JULES expects all these files to exist for +every run (even when their contents are not required). JULES also expects that +the namelists within each file appear in the order given below. .. toctree:: :maxdepth: 2 @@ -46,7 +48,7 @@ These files have specific names, and JULES expects all these files to exist for cable_soilparm.nml crop_params.nml triffid_params.nml - red_params.nml + red_parms.nml urban.nml fire.nml drive.nml diff --git a/doc/source/namelists/crop_params.nml.rst b/doc/source/namelists/crop_params.nml.rst index a440caa6..deb410ed 100644 --- a/doc/source/namelists/crop_params.nml.rst +++ b/doc/source/namelists/crop_params.nml.rst @@ -1,245 +1,244 @@ -``crop_params.nml`` -=================== - - -This file contains a single namelist called :nml:lst:`JULES_CROPPARM` that sets time- and space-invariant parameters for each crop type. - - -``JULES_CROPPARM`` namelist members ------------------------------------ - -.. nml:namelist:: JULES_CROPPARM - -This namelist reads the values of parameters for each of the crop functional types. These parameters are a function of crop pft only. These parameters are only required if :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0. The crop pfts should be in the same order as in :doc:`pft_params.nml`. - -.. seealso:: - References: - - * Osborne et al, `JULES-crop: a parametrisation of crops in the Joint UK Land Environment Simulator `_, Geosci. Model Dev., 8, 1139-1155, 2015. - - Parameters introduced after the Osborne et al 2015 paper are described in the appendix of - - * Williams et al, `Evaluation of JULES-crop performance against site observations of irrigated maize from Mead, Nebraska `_, Geosci. Model Dev., 10, 1291-1320, 2017. - -.. nml:member:: t_bse_io - - :type: real(ncpft) - :default: None - - Base temperature (K). - - -.. nml:member:: t_opt_io - - :type: real(ncpft) - :default: None - - Optimum temperature (K). - - -.. nml:member:: tmax_io - - :type: real(ncpft) - :default: None - - Maximum temperature (K). - - -.. nml:member:: tt_emr_io - - :type: real(ncpft) - :default: None - - Thermal time between sowing and emergence (deg Cd). - - -.. nml:member:: crit_pp_io - - :type: real(ncpft) - :default: None - - Critical photoperiod (hours). - - -.. nml:member:: pp_sens_io - - :type: real(ncpft) - :default: None - - Sensitivity of development rate to photoperiod (hours\ :sup:`-1`). - - -.. nml:member:: rt_dir_io - - :type: real(ncpft) - :default: None - - Coefficient determining relative growth of roots vertically and horizontally. - - -.. nml:member:: alpha1_io - - :type: real(ncpft) - :default: None - - Coefficient for determining partitioning. - - -.. nml:member:: alpha2_io - - :type: real(ncpft) - :default: None - - Coefficient for determining partitioning. - - -.. nml:member:: alpha3_io - - :type: real(ncpft) - :default: None - - Coefficient for determining partitioning. - - -.. nml:member:: beta1_io - - :type: real(ncpft) - :default: None - - Coefficient for determining partitioning. - - -.. nml:member:: beta2_io - - :type: real(ncpft) - :default: None - - Coefficient for determining partitioning. - - -.. nml:member:: beta3_io - - :type: real(ncpft) - :default: None - - Coefficient for determining partitioning. - - -.. nml:member:: gamma_io - - :type: real(ncpft) - :default: None - - Coefficient for determining specific leaf area (m\ :sup:`2` kg\ :sup:`-1`). - - -.. nml:member:: delta_io - - :type: real(ncpft) - :default: None - - Coefficient for determining specific leaf area (m\ :sup:`2` kg\ :sup:`-1`). - - -.. nml:member:: remob_io - - :type: real(ncpft) - :default: None - - Remobilisation factor. Fraction of stem growth partitioned to RESERVEC. - - -.. nml:member:: cfrac_s_io - - :type: real(npft) - :default: None - - Carbon fraction of dry matter for stems. - - -.. nml:member:: cfrac_r_io - - :type: real(ncpft) - :default: None - - Carbon fraction of dry matter for roots. - - -.. nml:member:: cfrac_l_io - - :type: real(ncpft) - :default: None - - Carbon fraction of dry matter for leaves. - - -.. nml:member:: allo1_io - - :type: real(ncpft) - :default: None - - Allometric coefficient relating STEMC to CANHT. - - -.. nml:member:: allo2_io - - :type: real(ncpft) - :default: None - - Allometric coefficient relating STEMC to CANHT. - - -.. nml:member:: mu_io - - :type: real(ncpft) - :default: None - - Allometric coefficient for calculation of senescence. MIN(mu_io * (dvi - sen_dvi_io) ** nu_io, 1.0) is the fraction of leaf carbon that is moved to the harvest pool per day once senescence has started. - - -.. nml:member:: nu_io - - :type: real(ncpft) - :default: None - - Allometric coefficient for calculation of senescence. See description for :nml:mem:`mu_io` - - -.. nml:member:: yield_frac_io - - :type: real(ncpft) - :default: None - - Fraction of the harvest carbon pool converted to yield carbon (yield is the economically valuable component of the harvest pool e.g. kernel). - - -.. nml:member:: initial_carbon_io - - :type: real(ncpft) - :default: None - - Carbon in crop at emergence in kgC/m2. - - -.. nml:member:: initial_c_dvi_io - - :type: real(ncpft) - :default: None - - DVI at which the crop carbon is set to :nml:mem:`initial_carbon_io`. Should be at emergence (0.0) or shortly after. - - -.. nml:member:: sen_dvi_io - - :type: real(ncpft) - :default: None - - DVI at which leaf senescence begins. - - -.. nml:member:: t_mort_io - - :type: real(ncpft) - :default: None - - Soil temperature (second level) at which to kill crop if DVI>1. +``crop_params.nml`` +=================== + +This file contains a single namelist called :nml:lst:`JULES_CROPPARM` that sets time- and space-invariant parameters for each crop type. + + +``JULES_CROPPARM`` namelist members +----------------------------------- + +.. nml:namelist:: JULES_CROPPARM + +This namelist reads the values of parameters for each of the crop functional types. These parameters are a function of crop pft only. These parameters are only required if :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0. The crop pfts should be in the same order as in :doc:`pft_params.nml`. + +.. seealso:: + References: + + * Osborne et al, `JULES-crop: a parametrisation of crops in the Joint UK Land Environment Simulator `_, Geosci. Model Dev., 8, 1139-1155, 2015. + + Parameters introduced after the Osborne et al 2015 paper are described in the appendix of + + * Williams et al, `Evaluation of JULES-crop performance against site observations of irrigated maize from Mead, Nebraska `_, Geosci. Model Dev., 10, 1291-1320, 2017. + +.. nml:member:: t_bse_io + + :type: real(ncpft) + :default: None + + Base temperature (K). + + +.. nml:member:: t_opt_io + + :type: real(ncpft) + :default: None + + Optimum temperature (K). + + +.. nml:member:: tmax_io + + :type: real(ncpft) + :default: None + + Maximum temperature (K). + + +.. nml:member:: tt_emr_io + + :type: real(ncpft) + :default: None + + Thermal time between sowing and emergence (deg Cd). + + +.. nml:member:: crit_pp_io + + :type: real(ncpft) + :default: None + + Critical photoperiod (hours). + + +.. nml:member:: pp_sens_io + + :type: real(ncpft) + :default: None + + Sensitivity of development rate to photoperiod (hours\ :sup:`-1`). + + +.. nml:member:: rt_dir_io + + :type: real(ncpft) + :default: None + + Coefficient determining relative growth of roots vertically and horizontally. + + +.. nml:member:: alpha1_io + + :type: real(ncpft) + :default: None + + Coefficient for determining partitioning. + + +.. nml:member:: alpha2_io + + :type: real(ncpft) + :default: None + + Coefficient for determining partitioning. + + +.. nml:member:: alpha3_io + + :type: real(ncpft) + :default: None + + Coefficient for determining partitioning. + + +.. nml:member:: beta1_io + + :type: real(ncpft) + :default: None + + Coefficient for determining partitioning. + + +.. nml:member:: beta2_io + + :type: real(ncpft) + :default: None + + Coefficient for determining partitioning. + + +.. nml:member:: beta3_io + + :type: real(ncpft) + :default: None + + Coefficient for determining partitioning. + + +.. nml:member:: gamma_io + + :type: real(ncpft) + :default: None + + Coefficient for determining specific leaf area (m\ :sup:`2` kg\ :sup:`-1`). + + +.. nml:member:: delta_io + + :type: real(ncpft) + :default: None + + Coefficient for determining specific leaf area (m\ :sup:`2` kg\ :sup:`-1`). + + +.. nml:member:: remob_io + + :type: real(ncpft) + :default: None + + Remobilisation factor. Fraction of stem growth partitioned to RESERVEC. + + +.. nml:member:: cfrac_s_io + + :type: real(npft) + :default: None + + Carbon fraction of dry matter for stems. + + +.. nml:member:: cfrac_r_io + + :type: real(ncpft) + :default: None + + Carbon fraction of dry matter for roots. + + +.. nml:member:: cfrac_l_io + + :type: real(ncpft) + :default: None + + Carbon fraction of dry matter for leaves. + + +.. nml:member:: allo1_io + + :type: real(ncpft) + :default: None + + Allometric coefficient relating STEMC to CANHT. + + +.. nml:member:: allo2_io + + :type: real(ncpft) + :default: None + + Allometric coefficient relating STEMC to CANHT. + + +.. nml:member:: mu_io + + :type: real(ncpft) + :default: None + + Allometric coefficient for calculation of senescence. MIN(mu_io * (dvi - sen_dvi_io) ** nu_io, 1.0) is the fraction of leaf carbon that is moved to the harvest pool per day once senescence has started. + + +.. nml:member:: nu_io + + :type: real(ncpft) + :default: None + + Allometric coefficient for calculation of senescence. See description for :nml:mem:`mu_io` + + +.. nml:member:: yield_frac_io + + :type: real(ncpft) + :default: None + + Fraction of the harvest carbon pool converted to yield carbon (yield is the economically valuable component of the harvest pool e.g. kernel). + + +.. nml:member:: initial_carbon_io + + :type: real(ncpft) + :default: None + + Carbon in crop at emergence in kgC/m2. + + +.. nml:member:: initial_c_dvi_io + + :type: real(ncpft) + :default: None + + DVI at which the crop carbon is set to :nml:mem:`initial_carbon_io`. Should be at emergence (0.0) or shortly after. + + +.. nml:member:: sen_dvi_io + + :type: real(ncpft) + :default: None + + DVI at which leaf senescence begins. + + +.. nml:member:: t_mort_io + + :type: real(ncpft) + :default: None + + Soil temperature (second level) at which to kill crop if DVI>1. diff --git a/doc/source/namelists/drive.nml.rst b/doc/source/namelists/drive.nml.rst index 1672b14a..93ba453f 100644 --- a/doc/source/namelists/drive.nml.rst +++ b/doc/source/namelists/drive.nml.rst @@ -1,7 +1,6 @@ ``drive.nml`` ============= - This file contains a single namelist called :nml:lst:`JULES_DRIVE` that indicates how meteorological driving data is input. @@ -23,7 +22,7 @@ This file contains a single namelist called :nml:lst:`JULES_DRIVE` that indicate :type: real :default: None - If total preciption or total rainfall are given, then :nml:mem:`t_for_con_rain` is the near-surface air temperature (K) at or above which rainfall is assumed to be convective in origin. At lower temperatures, all the rainfall is assumed to be large-scale in origin. In this configuration all snow is assumed to be large-scale in origin. The default value used to be 373.15 K but in general this is not recommended as it effectively means all precipitation is large-scale; a value of 293.15 K might be more appropriate. + If total precipitation or total rainfall are given, then :nml:mem:`t_for_con_rain` is the near-surface air temperature (K) at or above which rainfall is assumed to be convective in origin. At lower temperatures, all the rainfall is assumed to be large-scale in origin. In this configuration all snow is assumed to be large-scale in origin. The default value used to be 373.15 K but in general this is not recommended as it effectively means all precipitation is large-scale; a value of 293.15 K might be more appropriate. Also see :nml:mem:`JULES_SOIL::confrac`. @@ -53,81 +52,81 @@ This file contains a single namelist called :nml:lst:`JULES_DRIVE` that indicate TRUE Disaggregator is used. - + .. warning:: The disaggregator requires: - + #. Daily forcing data, i.e. :nml:mem:`data_period` = 86400 #. :nml:mem:`JULES_TIME::main_run_start`, :nml:mem:`JULES_SPINUP::spinup_start` and :nml:mem:`data_start` to be 00:00:00 for some day. FALSE Disaggregator is not used. - - + + .. nml:member:: l_disagg_const_rh - + :type: logical :default: F Switch controlling sub-daily disaggregation of humidity. - + Only used if :nml:mem:`l_daily_disagg` = TRUE. TRUE - Relative humidity is kept constant over day. + Relative humidity is kept constant over day. FALSE Specific humidity is kept constant over day (apart from when limited by specific humidity at saturation). - - + + .. nml:member:: dur_conv_rain :type: real :default: None Duration of a convective rainfall event in seconds for use in the disaggregator. See HCTN96 section 2.4. A value of 21600s (6 hours) used to be the default. - + Only used if :nml:mem:`l_daily_disagg` = TRUE. - - + + .. nml:member:: dur_ls_rain :type: real :default: None Duration of a large-scale rainfall event in seconds for use in the disaggregator. See HCTN96 section 2.4. A value of 3600s (1 hour) used to be the default. - + Only used if :nml:mem:`l_daily_disagg` = TRUE. - - + + .. nml:member:: dur_conv_snow :type: real :default: None Duration of a convective snowfall event in seconds for use in the disaggregator. See HCTN96 section 2.4. A value of 3600s (1 hour) used to be the default. - + Only used if :nml:mem:`l_daily_disagg` = TRUE. - - + + .. nml:member:: dur_ls_snow :type: real :default: None Duration of a large-scale snowfall event in seconds for use in the disaggregator. See HCTN96 section 2.4. A value of 3600s (1 hour) used to be the default. - + Only used if :nml:mem:`l_daily_disagg` = TRUE. - - - .. nml:member:: precip_disagg_method + + + .. nml:member:: precip_disagg_method :type: integer :permitted: 1, 2, 3 or 4 :default: None Switch controlling the disaggregation method for precipitation. See HCTN96 section 2.4. The default value used to be 2. - + Only used if :nml:mem:`l_daily_disagg` = TRUE. 1. Do not disaggregate precipitation. @@ -161,7 +160,7 @@ This file contains a single namelist called :nml:lst:`JULES_DRIVE` that indicate :default: None Relative perturbation for precipitation variables (a multiplicative factor). Only used if :nml:mem:`l_perturb_driving` = TRUE. - + .. nml:group:: Members used to specify ``z1_tq`` and ``z1_uv`` @@ -176,15 +175,15 @@ This file contains a single namelist called :nml:lst:`JULES_DRIVE` that indicate .. nml:member:: z1_tq_vary - :type: logical - :default: F - - Switch to indicate whether ``z1_tq`` (the height (m) at which the temperature and humidity data are valid) should be constant for all points or spatially varying. The height is relative to the zero-plane, not the ground. + :type: logical + :default: F + + Switch to indicate whether ``z1_tq`` (the height (m) at which the temperature and humidity data are valid) should be constant for all points or spatially varying. The height is relative to the zero-plane, not the ground. - TRUE - Spatially varying ``z1_tq`` will be read from the file specified in :nml:mem:`z1_tq_file`. + TRUE + Spatially varying ``z1_tq`` will be read from the file specified in :nml:mem:`z1_tq_file`. - FALSE + FALSE ``z1_tq`` will be set to a constant value, specified in :nml:mem:`z1_tq_in`, at all points. @@ -195,35 +194,35 @@ This file contains a single namelist called :nml:lst:`JULES_DRIVE` that indicate :default: None Constant value for ``z1_tq`` to be used for every point. - + Only required if :nml:mem:`z1_tq_vary` = F. - .. nml:member:: z1_tq_file + .. nml:member:: z1_tq_file + + :type: character + :default: None - :type: character - :default: None - File to read spatially varying ``z1_tq`` from. - + Only required if :nml:mem:`z1_tq_vary` = T. - .. nml:member:: z1_tq_var_name + .. nml:member:: z1_tq_var_name - :type: character + :type: character :default: 'z1_tq_in' The name of the variable in :nml:mem:`z1_tq_file` containing the data for ``z1_tq``. - + The variable should have no levels dimensions and no time dimension. - + .. note:: This is not used for ASCII files. - + However, since ASCII files can only be used for single-point runs, it is recommended to set :nml:mem:`z1_tq_vary` = F and use :nml:mem:`z1_tq_in` anyway. - + .. nml:group:: Members used to specify boundary layer height .. nml:member:: bl_height @@ -234,34 +233,34 @@ This file contains a single namelist called :nml:lst:`JULES_DRIVE` that indicate Height above ground to top of the atmospheric boundary layer (m). This value is disregarded if ``bl_height`` is provided as prescribed data (see :ref:`supported-prescribed-variables`). - + .. nml:group:: Members used to specify the start, end and period of the data .. nml:member:: data_start .. nml:member:: data_end - + :type: character :default: None - + The times of the start of the first timestep of data and the end of the last timestep of data. - + Each run of JULES (configured in :doc:`timesteps.nml`) can use part or all of the specified data. However, there must be data for all times between run start and run end (determined by :nml:mem:`JULES_TIME::main_run_start`, :nml:mem:`JULES_TIME::main_run_end`, :nml:mem:`JULES_SPINUP::spinup_start` and :nml:mem:`JULES_SPINUP::spinup_end`). - + The times must be given in the format:: - + "yyyy-mm-dd hh:mm:ss" - - + + .. nml:member:: data_period - + :type: integer :permitted: -2, -1 or > 0 :default: None - + The period, in seconds, of the data. - + Special cases: - + | **-1:** Monthly data | **-2:** Yearly data @@ -269,94 +268,94 @@ This file contains a single namelist called :nml:lst:`JULES_DRIVE` that indicate .. nml:group:: Members used to specify the files containing the data .. nml:member:: read_list - + :type: logical :default: F - + Switch controlling how data file names are determined for a given time. - + TRUE Use a list of data file names with times of first data. - + FALSE Use a single data file for all times or a template describing the names of the data files. - - + + .. nml:member:: nfiles - + :type: integer :permitted: >= 0 :default: 0 - + Only used if :nml:mem:`read_list` = TRUE. - + The number of data files to read name and time of first data for. - - + + .. nml:member:: file - + :type: character :default: None - + If :nml:mem:`read_list` = TRUE, this is the file to read the list of data file names and times from. Each line should be of the form:: - + '/data/file', 'yyyy-mm-dd hh:mm:ss' - + In this case data file names may contain variable name templating only, with the proviso that either no file names use variable name templating or all file names do. The files must appear in chronological order. - + If :nml:mem:`read_list` = FALSE, this is either the single data file (if no templating is used) or a template for data file names. Both :doc:`time and variable name templating ` may be used. .. nml:group:: Members used to specify the provided variables .. nml:member:: nvars - + :type: integer :permitted: >= 0 :default: 0 - + The number of forcing variables that will be provided. - + See :ref:`list-of-jules-forcing-variables` for the available forcing variables and their possible configurations. - - + + .. nml:member:: var - + :type: character(nvars) :default: None - + List of forcing variable names as recognised by JULES (see :ref:`list-of-jules-forcing-variables`). Names are case sensitive. - + .. note:: For ASCII files, variable names must be in the order they appear in the file. - - + + .. nml:member:: var_name - + :type: character(nvars) :default: '' (empty string) - + For each JULES variable specified in :nml:mem:`var`, this is the name of the variable in the file(s) containing the data. If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. - + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. - - + + .. nml:member:: tpl_name - + :type: character(nvars) :default: None - + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name(s) in place of the variable name substitution string. - + If the file name(s) do not use variable name templating, this is not used. - - + + .. nml:member:: interp - + :type: character(nvars) :default: None - + For each JULES variable specified in :nml:mem:`var`, this indicates how the variable is to be interpolated in time (see :doc:`/input/temporal-interpolation`). @@ -370,15 +369,15 @@ All of the available forcing variables listed in the sections below, are expecte Pressure, Humidity and Temperature ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| Name | Description | -+============================+===========================================================================================================+ -| ``pstar`` | Air pressure (Pa). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``q`` | Specific humidity (kg kg\ :sup:`-1`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``t`` | Air temperature (K). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ ++-----------------+-----------------------------------------+ +| Name | Description | ++=================+=========================================+ +| ``pstar`` | Air pressure (Pa). | ++-----------------+-----------------------------------------+ +| ``q`` | Specific humidity (kg kg\ :sup:`-1`). | ++-----------------+-----------------------------------------+ +| ``t`` | Air temperature (K). | ++-----------------+-----------------------------------------+ Radiation variables ^^^^^^^^^^^^^^^^^^^ @@ -403,21 +402,21 @@ If any of the four combinations of radiation variables listed above are provided ``diff_rad`` can be used with any of the four methods. If it is given, diffuse radiation is input from file. If it is not given, :nml:mem:`JULES_DRIVE::diff_frac_const` is used instead to partition the downward shortwave radiation into diffuse and direct. -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| Name | Description | -+============================+===========================================================================================================+ -| ``rad_net`` | Net (all wavelength) downward radiation (W m\ :sup:`-2`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``lw_net`` | Net downward longwave radiation (W m\ :sup:`-2`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``sw_net`` | Net downward shortwave radiation (W m\ :sup:`-2`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``lw_down`` | Downward longwave radiation (W m\ :sup:`-2`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``sw_down`` | Downward shortwave radiation (W m\ :sup:`-2`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``diff_rad`` | Diffuse radiation (W m\ :sup:`-2`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ ++--------------+-----------------------------------------------------------+ +| Name | Description | ++==============+===========================================================+ +| ``rad_net`` | Net (all wavelength) downward radiation (W m\ :sup:`-2`). | ++--------------+-----------------------------------------------------------+ +| ``lw_net`` | Net downward longwave radiation (W m\ :sup:`-2`). | ++--------------+-----------------------------------------------------------+ +| ``sw_net`` | Net downward shortwave radiation (W m\ :sup:`-2`). | ++--------------+-----------------------------------------------------------+ +| ``lw_down`` | Downward longwave radiation (W m\ :sup:`-2`). | ++--------------+-----------------------------------------------------------+ +| ``sw_down`` | Downward shortwave radiation (W m\ :sup:`-2`). | ++--------------+-----------------------------------------------------------+ +| ``diff_rad`` | Diffuse radiation (W m\ :sup:`-2`). | ++--------------+-----------------------------------------------------------+ Precipitation variables ^^^^^^^^^^^^^^^^^^^^^^^ @@ -442,23 +441,23 @@ The concept of convective and large-scale (or dynamical) components of precipita .. warning:: If :nml:mem:`l_daily_disagg` = TRUE, then :nml:mem:`interp` for each precipitation variable should be ``f`` or ``nf``. -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| Name | Description | -+============================+===========================================================================================================+ -| ``precip`` | Precipitation rate (kg m\ :sup:`-2` s\ :sup:`-1`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``tot_rain`` | Rainfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``tot_snow`` | Snowfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``ls_rain`` | Large-scale rainfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``con_rain`` | Convective rainfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``ls_snow`` | Large-scale snowfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``con_snow`` | Convective snowfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ ++---------------+-------------------------------------------------------------+ +| Name | Description | ++===============+=============================================================+ +| ``precip`` | Precipitation rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++---------------+-------------------------------------------------------------+ +| ``tot_rain`` | Rainfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++---------------+-------------------------------------------------------------+ +| ``tot_snow`` | Snowfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++---------------+-------------------------------------------------------------+ +| ``ls_rain`` | Large-scale rainfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++---------------+-------------------------------------------------------------+ +| ``con_rain`` | Convective rainfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++---------------+-------------------------------------------------------------+ +| ``ls_snow`` | Large-scale snowfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++---------------+-------------------------------------------------------------+ +| ``con_snow`` | Convective snowfall rate (kg m\ :sup:`-2` s\ :sup:`-1`). | ++---------------+-------------------------------------------------------------+ Wind variables ^^^^^^^^^^^^^^ @@ -473,15 +472,15 @@ The wind variables can be given in one of two ways: If ``wind`` is given, then the first method is used. The second method is used in all other cases. -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| Name | Description | -+============================+===========================================================================================================+ -| ``wind`` | Total wind speed (m s\ :sup:`-1`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``u`` | Zonal component of the wind (m s\ :sup:`-1`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| ``v`` | Meridional component of the wind (m s\ :sup:`-1`). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ ++------------+----------------------------------------------------------------+ +| Name | Description | ++============+================================================================+ +| ``wind`` | Total wind speed (m s\ :sup:`-1`). | ++------------+----------------------------------------------------------------+ +| ``u`` | Zonal component of the wind (m s\ :sup:`-1`). | ++------------+----------------------------------------------------------------+ +| ``v`` | Meridional component of the wind (m s\ :sup:`-1`). | ++------------+----------------------------------------------------------------+ Daily disaggregator variables @@ -489,11 +488,11 @@ Daily disaggregator variables If :nml:mem:`l_daily_disagg` = TRUE, then the diurnal temperature range is also required: -+----------------------------+-----------------------------------------------------------------------------------------------------------+ -| Name | Description | -+============================+===========================================================================================================+ -| ``dt_range`` | Diurnal temperature range (K). | -+----------------------------+-----------------------------------------------------------------------------------------------------------+ ++---------------+-------------------------------------------------------------+ +| Name | Description | ++===============+=============================================================+ +| ``dt_range`` | Diurnal temperature range (K). | ++---------------+-------------------------------------------------------------+ Examples of specifying driving data @@ -583,5 +582,3 @@ The presence of the variable name templating string in each file name shows that Furthermore, files for each variable are stored in separate directories. The values from :nml:mem:`JULES_DRIVE::tpl_name` will be substituted into the file name templates in place of the substitution string (``%vv``). For example, pressure is held in files with names like ``met_data/PSurf_data/PSurf198207.nc``, and temperature in files like ``met_data/Tair_data/Tair198207.nc``. The driving variable setup is as the previous example. - - diff --git a/doc/source/namelists/fire.nml.rst b/doc/source/namelists/fire.nml.rst index 899f7c4d..96c8f492 100644 --- a/doc/source/namelists/fire.nml.rst +++ b/doc/source/namelists/fire.nml.rst @@ -22,7 +22,6 @@ This file contains a single namelist called :nml:lst:`FIRE_SWITCHES` that sets t The fire module will not be executed and subsequent members of the namelist will have no effect. - .. nml:member:: mcarthur_flag :type: boolean diff --git a/doc/source/namelists/imogen.nml.rst b/doc/source/namelists/imogen.nml.rst index 8090bd12..6e5b4629 100644 --- a/doc/source/namelists/imogen.nml.rst +++ b/doc/source/namelists/imogen.nml.rst @@ -1,16 +1,15 @@ ``imogen.nml`` ============== - This file contains three namelists called :nml:lst:`IMOGEN_ONOFF_SWITCH`, :nml:lst:`IMOGEN_RUN_LIST` and :nml:lst:`IMOGEN_ANLG_VALS_LIST`. Values from this section are only used if IMOGEN is enabled. This is done via the following switch: :nml:mem:`IMOGEN_ONOFF_SWITCH::l_imogen` = TRUE. 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 files to derive the driving data. The driving data is derived from: 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`. +IMOGEN uses the netcdf read functions in JULES to load the files to derive the driving data. The driving data is derived from: specific humidity (kg/kg), precipitation (kg/m2/s), wind speed (m/s), incoming shortwave radiation (W/m2), incoming longwave radiation (W/m2), air temperature (K) and diurnal range of air temperature (K). IMOGEN also needs ``grid_area`` read in via :nml:lst:`JULES_LATLON`. IMOGEN can either take a daily or a monthly climatology to drive JULES. This is controlled by :nml:mem:`IMOGEN_ONOFF_SWITCH::l_daily_metdata_climatol`. If the driving data changes during runtime (:nml:mem:`IMOGEN_RUN_LIST::l_change_metdata` = TRUE) there are different methods for changing it (:nml:mem:`IMOGEN_RUN_LIST::change_metdata_method`). -If :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` = 2, then use anomalies from the given climatology. Otherwise (:nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` set to 1 or 3) use pattern-scaling (spatial patterns of changes in each meteorological driving variable per degree of global temperature change). Patterns can be derived at the required spatial resolution using ESMValTool . +If :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` = 2, then use anomalies from the given climatology. Otherwise (:nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` set to 1 or 3) use pattern-scaling (spatial patterns of changes in each meteorological driving variable per degree of global temperature change). Patterns can be derived at the required spatial resolution using `ESMValTool `__. If :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` = 3, then IMOGEN reads the global mean temperature change via the :nml:lst:`JULES_PRESCRIBED`. IMOGEN still reads the other 1d data from ascii files - this will change in the near future. @@ -21,7 +20,7 @@ If :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` = 3, then IMOGEN reads the An analogue model to derive additional climate change scenarios from existing GCM simulations, Climate Dynamics 16(8): 575-586. https://doi.org/10.1007/s003820000067 - * Huntingford, C., et al. (2010), + * Huntingford, C., et al. (2010), IMOGEN: an intermediate complexity model to evaluate terrestrial impacts of a changing climate, Geoscientific Model Development 3(2): 679-687. @@ -32,12 +31,12 @@ If :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` = 3, then IMOGEN reads the Nature Geoscience 11(8): 568-573. https://doi.org/10.1038/s41561-018-0174-9 * Zelazowski, P., et al. (2018), - Climate pattern-scaling set for an ensemble of 22 - GCMs–adding uncertainty to the IMOGEN version 2.0 impact system, + Climate pattern-scaling set for an ensemble of 22 + GCMs-adding uncertainty to the IMOGEN version 2.0 impact system, Geoscientific Model Development 11.2: 541-560. https://doi.org/10.5194/gmd-11-541-2018 * Mathison, C., et al. (2024), - A rapid application emissions-to-impacts tool for scenario assessment: + A rapid application emissions-to-impacts tool for scenario assessment: Probabilistic Regional Impacts from Model patterns and Emissions (PRIME), Geoscientific Model Development. https://doi.org/10.5194/egusphere-2023-2932, 2024 @@ -60,7 +59,7 @@ If :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` = 3, then IMOGEN reads the FALSE No effect. - + .. note:: If IMOGEN is enabled, at most only :nml:mem:`JULES_DRIVE::z1_tq_vary`, :nml:mem:`JULES_DRIVE::z1_tq_in`, :nml:mem:`JULES_DRIVE::z1_uv_in`, :nml:mem:`JULES_DRIVE::z1_tq_file` and :nml:mem:`JULES_DRIVE::z1_tq_var_name` are used from the :nml:lst:`JULES_DRIVE` namelist. @@ -106,7 +105,7 @@ If :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` = 3, then IMOGEN reads the If used, file containing non-CO2 radiative forcing values. This file is expected to be in a specific format - see the IMOGEN example. - + .. nml:member:: nyr_non_co2 @@ -196,6 +195,14 @@ If :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` = 3, then IMOGEN reads the Only if :nml:mem:`land_feed_ch4` = TRUE. +.. nml:member:: l_drive_with_global_temps + + :type: logical + :default: F + + If TRUE, use imogen to provide jules forcing based on the global mean temperature change and the climate patterns. + + .. nml:member:: l_change_metdata :type: logical @@ -217,8 +224,8 @@ If :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` = 3, then IMOGEN reads the 1. | IMOGEN provides jules forcing based on the analogue model and spatial patterns of sensitivity to global mean temperature change. | This can including changing atmospheric CO2 (:nml:mem:`include_co2` = TRUE) and can be emissions driven (:nml:mem:`c_emissions` = True) or concentration driven (:nml:mem:`c_emissions` = False) | Feedbacks can be included (:nml:mem:`land_feed_ch4`, :nml:mem:`land_feed_co2`, :nml:mem:`ocean_feed`) - | An additional non-CO2 rdiative forcing can also be prescribed (:nml:mem:`file_non_co2_radf`). - 2. | Time series of anomaly data provided + | An additional non-CO2 radiative forcing can also be prescribed (:nml:mem:`file_non_co2_radf`). + 2. | Time series of anomaly data provided | Requires CO2 concentration data (:nml:mem:`include_co2` = TRUE and :nml:mem:`c_emissions` = False) | Currently no feedbacks included 3. | IMOGEN provides jules forcing based on the global mean temperature change and the climate patterns. @@ -400,7 +407,7 @@ If :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` = 3, then IMOGEN reads the :type: character :default: None - Netcdf file containing the patterns. It should be monthly data (12 months total) with the dimension 'imogen_drive' representing time. + Netcdf file containing the patterns. It should be monthly data (12 months total) with the dimension 'imogen_drive' representing time. .. nml:member:: file_clim @@ -417,7 +424,3 @@ If :nml:mem:`IMOGEN_RUN_LIST::change_metdata_method` = 3, then IMOGEN reads the :default: None 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/doc/source/namelists/initial_conditions.nml.rst b/doc/source/namelists/initial_conditions.nml.rst index 914e8f5c..3d70b899 100644 --- a/doc/source/namelists/initial_conditions.nml.rst +++ b/doc/source/namelists/initial_conditions.nml.rst @@ -1,7 +1,6 @@ ``initial_conditions.nml`` ========================== - This file contains a single namelist called :nml:lst:`JULES_INITIAL` that is used to set up the initial state of prognostic variables. diff --git a/doc/source/namelists/intro.rst b/doc/source/namelists/intro.rst index 006813bd..75929e83 100644 --- a/doc/source/namelists/intro.rst +++ b/doc/source/namelists/intro.rst @@ -18,13 +18,13 @@ Values for character variables must be enclosed in either single(' ') or double identical:: list_variable = 0.1 0.2 0.3 0.4 0.5 - + list_variable(1) = 0.1 list_variable(2) = 0.2 list_variable(3) = 0.3 list_variable(4) = 0.4 list_variable(5) = 0.5 - + Namelists are an ideal input mechanism for programs like JULES that have a large number of inputs, most of which users never change from the default. Since each variable can have a sensible default value specified in the code, the user need only specify variables they wish to change from the default. This can substantially reduce the size and complexity of the namelist files. For example, suppose that in the above example the namelist member ``logical_variable`` has a default value of ``.TRUE.``. Then the following namelist specification is equivalent to that above:: diff --git a/doc/source/namelists/jules_deposition.nml.rst b/doc/source/namelists/jules_deposition.nml.rst index ed466c5b..a526be63 100644 --- a/doc/source/namelists/jules_deposition.nml.rst +++ b/doc/source/namelists/jules_deposition.nml.rst @@ -21,7 +21,7 @@ This file contains options and parameters for modelling of dry deposition of atm :default: FALSE Switch to activate deposition code in JULES. - + TRUE Model deposition in JULES. @@ -61,7 +61,7 @@ This file contains options and parameters for modelling of dry deposition of atm 1. | Parameterisation based on Conrad & Seiler uptake scheme in the UKCA. 2. | Parameterisation based on Paulot et al. scheme. - Note: The Paulot et al. scheme is currently not available in UM-coupled JULES applications. + Note: The Paulot et al. scheme is currently not available in UM-coupled JULES applications. .. nml:member:: l_deposition_flux @@ -72,7 +72,7 @@ This file contains options and parameters for modelling of dry deposition of atm Switch for calculation of deposition fluxes as opposed to deposition velocities. TRUE - Calculate deposition fluxes. This requires that the concentrations of atmopsheric tracer species are provided as prescribed data (see :ref:`supported-prescribed-variables`). + Calculate deposition fluxes. This requires that the concentrations of atmospheric tracer species are provided as prescribed data (see :ref:`supported-prescribed-variables`). FALSE Calculate deposition velocities. @@ -92,7 +92,7 @@ This file contains options and parameters for modelling of dry deposition of atm :type: real :default: none - Latitude of southern limit of tundra (radians). This is used to alter the calculation of deposition of certain species in the tundra region (actually for all points north of this limit). Only used if the list of species (see :nml:mem:`JULES_DEPOSITION_SPECIES::dep_species_name_io`) includes one or more of 'CO', 'NO2', 'O3', 'PAN', 'PPAN', 'MPAN' or 'ONITU'. + Latitude of southern limit of tundra (radians). This is used to alter the calculation of deposition of certain species in the tundra region (actually for all points north of this limit). Only used if the list of species (see :nml:mem:`JULES_DEPOSITION_SPECIES::dep_species_name_io`) includes one or more of 'CO', 'NO2', 'O3', 'PAN', 'PPAN', 'MPAN' or 'ONITU'. .. nml:member:: dzl_const @@ -100,7 +100,7 @@ This file contains options and parameters for modelling of dry deposition of atm :type: real :default: none - Constant value for separation of boundary layer levels (m). All layer thicknesses are set to this value. This is used as a simple way to prescribe the layer thicknesses in standalone mode. This value can be overriden by prescribed data - see :nml:lst:`JULES_PRESCRIBED`. This can be considered as the representative depth for tracer concentration and the depth over which the deposition flux is removed. + Constant value for separation of boundary layer levels (m). All layer thicknesses are set to this value. This is used as a simple way to prescribe the layer thicknesses in standalone mode. This value can be overridden by prescribed data - see :nml:lst:`JULES_PRESCRIBED`. This can be considered as the representative depth for tracer concentration and the depth over which the deposition flux is removed. .. nml:member:: l_deposition_from_ukca @@ -142,7 +142,7 @@ This file contains options and parameters for modelling of dry deposition of atm :type: logical :default: FALSE - Switch from the UKCA controlling which atmospheric levels in the boundary layer are used for dry deposition. For UM-coupled JULES applications, the UKCA interactive dry deposition switch (l_ukca_intdd in the run_ukca namelist) needs to be true. + Switch from the UKCA controlling which atmospheric levels in the boundary layer are used for dry deposition. For UM-coupled JULES applications, the UKCA interactive dry deposition switch (l_ukca_intdd in the run_ukca namelist) needs to be true. TRUE Deposition occurs only from the lowest level in the atmospheric boundary layer. @@ -200,7 +200,7 @@ Notes on the ``JULES_DEPOSITION`` namelist The height of the atmospheric boundary layer is required and is set to a default constant value of 1000 m. This value can be overridden via the namelist variable :nml:mem:`JULES_DRIVE::bl_height`, or can be prescribed (i.e. allowed to vary in time and/or space) by providing ``bl_height`` as prescribed data (see :ref:`supported-prescribed-variables`). -The number of model levels in the boundary layer is required and is set to a default balues of 1. This can be overridden via the namelist variable :nml:mem:`JULES_NLSIZES::bl_levels`. The number of levels is only used to communicate with the atmospheric model (e.g. UKCA). +The number of model levels in the boundary layer is required and is set to a default values of 1. This can be overridden via the namelist variable :nml:mem:`JULES_NLSIZES::bl_levels`. The number of levels is only used to communicate with the atmospheric model (e.g. UKCA). The separation of the model levels in the boundary layer is required and is set to a constant value via :nml:mem:`dzl_const`. The separation can be prescribed (i.e. allowed to vary in time and/or space) by providing ``level_separation`` as prescribed data (see :ref:`supported-prescribed-variables`). This can be considered as the representative depth for tracer concentration and the depth over which the deposition flux is removed. @@ -212,7 +212,7 @@ If deposition fluxes (rather than deposition velocities) are to be calculated (s .. nml:namelist:: JULES_DEPOSITION_SPECIES -This namelist should occur :nml:mem:`JULES_DEPOSITION::ndry_dep_species` times, with each occurence containing parameters for an atmospheric tracer species that is to be considered in dry deposition. +This namelist should occur :nml:mem:`JULES_DEPOSITION::ndry_dep_species` times, with each occurrence containing parameters for an atmospheric tracer species that is to be considered in dry deposition. .. nml:member:: dep_species_name_io diff --git a/doc/source/namelists/jules_hydrology.nml.rst b/doc/source/namelists/jules_hydrology.nml.rst index eed5d792..b72be45e 100644 --- a/doc/source/namelists/jules_hydrology.nml.rst +++ b/doc/source/namelists/jules_hydrology.nml.rst @@ -1,11 +1,9 @@ ``jules_hydrology.nml`` ======================= - This file sets the hydrology options. It contains one namelist called :nml:lst:`JULES_HYDROLOGY`. - ``JULES_HYDROLOGY`` namelist members ------------------------------------- @@ -93,7 +91,7 @@ This file sets the hydrology options. It contains one namelist called :nml:lst:` :default: F TRUE - Limit the soil conductance to the value when the top layer soil moisture is at the critical soil moisture. Below this threshold, the soil conductance follows Best et al. (2011) equation 7. + Limit the soil conductance to the value when the top layer soil moisture is at the critical soil moisture. Below this threshold, the soil conductance follows Best et al. (2011) equation 7. FALSE Allow the soil conductance to increase as the top layer soil moisture goes above the critical soil moisture, as in Best et al. (2011) equation 7. @@ -199,7 +197,7 @@ This file sets the hydrology options. It contains one namelist called :nml:lst:` A value of 6.0 has been tested for slope fields calculated from a high resolution DEM dataset (50m IHDTM for Great Britain). - For slopes calculated from coarser DEM datasets, a lower value might be more appropriate as fine-resolution features of the terrain are not included. + For slopes calculated from coarser DEM datasets, a lower value might be more appropriate as fine-resolution features of the terrain are not included. .. nml:group:: Only used if :nml:mem:`l_spdmvar` = FALSE diff --git a/doc/source/namelists/jules_irrig.nml.rst b/doc/source/namelists/jules_irrig.nml.rst index 2f367f63..b3164086 100644 --- a/doc/source/namelists/jules_irrig.nml.rst +++ b/doc/source/namelists/jules_irrig.nml.rst @@ -56,11 +56,11 @@ This namelist specifies the different options available for setting up the irrig .. warning:: The irrigation supply code in JULES is still in development, - and is available in this release to support beta testing - activities. + and is available in this release to support beta testing + activities. Users should ensure that results are as expected, and provide - feedback where deficiencies are identified. + feedback where deficiencies are identified. FALSE Tiles will be irrigated to critical point from an unconstrained water supply. @@ -68,6 +68,8 @@ This namelist specifies the different options available for setting up the irrig This must be set to FALSE if :nml:mem:`JULES_WATER_RESOURCES::l_water_irrigation` = TRUE. +.. |oumlaut| replace:: ö + .. nml:member:: irr_crop :type: integer @@ -78,7 +80,7 @@ This namelist specifies the different options available for setting up the irrig on the gridbox) lasts the entire year. 1. Irrigation season is determined from driving data according to - :ref:`Döll & Siebert (2002)` method. No irrigation + :ref:`D|oumlaut|ll & Siebert (2002)` method. No irrigation is applied outside the irrigation season. 2. Irrigation season is determined by maximum dvi across all @@ -128,7 +130,7 @@ This namelist specifies the different options available for setting up the irrig Irrigation will be updated every :nml:mem:`nstep_irrig` timesteps. For example, with a model timestep of 1 hour, :nml:mem:`nstep_irrig` = 24 means that irrigation will be updated on the 24th timestep, i.e. daily updates. - :nml:mem:`nstep_irrig` = NINT(frequency of irrigation update (in sec)) / :nml:mem:`JULES_TIME::timestep_len`) + :nml:mem:`nstep_irrig` = NINT(frequency of irrigation update (in sec)) / :nml:mem:`JULES_TIME::timestep_len` .. _References_irrig: @@ -136,6 +138,6 @@ This namelist specifies the different options available for setting up the irrig ``JULES_IRRIG`` references ------------------------------- -* Döll, P., and Siebert, S., Global modeling of irrigation water +* D|oumlaut|ll, P., and Siebert, S., Global modeling of irrigation water requirements, Water Resour. Res., 38(4), https://doi.org/10.1029/2001WR000355, 2002. diff --git a/doc/source/namelists/jules_prnt_control.nml.rst b/doc/source/namelists/jules_prnt_control.nml.rst index 212b331f..f0b296c6 100644 --- a/doc/source/namelists/jules_prnt_control.nml.rst +++ b/doc/source/namelists/jules_prnt_control.nml.rst @@ -1,7 +1,6 @@ ``jules_prnt_control.nml`` ========================== - This file contains one namelist called :nml:lst:`JULES_PRNT_CONTROL`. This namelist sets options for output of diagnostic and informative messages. diff --git a/doc/source/namelists/jules_radiation.nml.rst b/doc/source/namelists/jules_radiation.nml.rst index 964a4d5b..20bf6490 100644 --- a/doc/source/namelists/jules_radiation.nml.rst +++ b/doc/source/namelists/jules_radiation.nml.rst @@ -1,11 +1,9 @@ ``jules_radiation.nml`` ======================= - This file sets the radiation options. It contains one namelist called :nml:lst:`JULES_RADIATION`. - ``JULES_RADIATION`` namelist members ------------------------------------- @@ -55,8 +53,8 @@ This file sets the radiation options. It contains one namelist called :nml:lst:` FALSE Produces both a direct ('black' sky) and a diffuse ('white' sky) albedo. - - + + .. nml:member:: l_niso_direct :type: logical @@ -90,7 +88,7 @@ This file sets the radiation options. It contains one namelist called :nml:lst:` FALSE Calculate albedo of snow using only snow depth. - + .. nml:member:: l_embedded_snow :type: logical @@ -103,7 +101,7 @@ This file sets the radiation options. It contains one namelist called :nml:lst:` FALSE No effect. - + .. nml:member:: l_mask_snow_orog :type: logical @@ -118,7 +116,7 @@ This file sets the radiation options. It contains one namelist called :nml:lst:` FALSE No effect. - + .. nml:member:: l_albedo_obs :type: logical @@ -139,8 +137,7 @@ This file sets the radiation options. It contains one namelist called :nml:lst:` :nml:mem:`JULES_RADIATION::l_spec_albedo` = FALSE the single (averaged) waveband albedo is required. - .. note:: Observed albedo(s) must be prescribed in - :doc:`prescribed_data.nml`. + .. note:: Observed albedo(s) must be prescribed in :doc:`prescribed_data.nml`. FALSE Do not scale the albedo values on tiles. @@ -201,15 +198,15 @@ This file sets the radiation options. It contains one namelist called :nml:lst:` Weights to form the overall albedo from its components (VIS direct, VIS diffuse, NIR direct, NIR diffuse) (Ideally, if :nml:mem:`JULES_RADIATION::l_partition_albsoil` = T, - :nml:mem:`JULES_RADIATION::wght_alb` and + :nml:mem:`JULES_RADIATION::wght_alb` and :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` should be consistent, with - :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` equal to + :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` equal to :math:`\sum_{3,4}` - :nml:mem:`JULES_RADIATION::wght_alb` :math:`/ \sum_1^4` + :nml:mem:`JULES_RADIATION::wght_alb` :math:`/ \sum_1^4` :nml:mem:`JULES_RADIATION::wght_alb`. - However, :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` - is applied only to bare soil and having a single parameter - is more transparent to the user, while + However, :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` + is applied only to bare soil and having a single parameter + is more transparent to the user, while :nml:mem:`JULES_RADIATION::wght_alb` is used only in diagnostics in standalone JULES and may have historical settings. Hence, the consistency of these two variables @@ -238,7 +235,7 @@ This file sets the radiation options. It contains one namelist called :nml:lst:` TRUE Partition the soil albedo between the visible and near infrared parts - of the spectrum using :nml:mem:`JULES_RADIATION::ratio_albsoil` and + of the spectrum using :nml:mem:`JULES_RADIATION::ratio_albsoil` and :nml:mem:`JULES_RADIATION::swdn_frac_albsoil`. FALSE @@ -260,29 +257,32 @@ This file sets the radiation options. It contains one namelist called :nml:lst:` The fraction of the total downward SW radiation assumed to be in the NIR part of the spectrum for partitioning the soil albedo. Used if :nml:mem:`JULES_RADIATION::l_partition_albsoil` = T. - (Ideally, :nml:mem:`JULES_RADIATION::wght_alb` and + (Ideally, :nml:mem:`JULES_RADIATION::wght_alb` and :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` should be consistent, with - :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` equal to + :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` equal to :math:`\sum_{3,4}` - :nml:mem:`JULES_RADIATION::wght_alb` :math:`/ \sum_1^4` + :nml:mem:`JULES_RADIATION::wght_alb` :math:`/ \sum_1^4` :nml:mem:`JULES_RADIATION::wght_alb`. - However, :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` is applied - only to bare soil and having a single parameter is more transparent + However, :nml:mem:`JULES_RADIATION::swdn_frac_albsoil` is applied + only to bare soil and having a single parameter is more transparent to the user, while :nml:mem:`JULES_RADIATION::wght_alb` is used only in diagnostics in standalone JULES and may have historical settings. Hence, the consistency of these two variables is not enforced.) +.. |eacute| replace:: é +.. |ccedil| replace:: ç + .. seealso:: References: * Barker, H.W. and Li, Z. (1995), Improved Simulation of Clear-Sky Shortwave Radiative Transfer in the CCC-GCM. J. Climate, 8, - 2213–2223, `doi:10.1175/1520-0442(1995)008<2213:ISOCSS>2.0.CO;2 + 2213-2223, `doi:10.1175/1520-0442(1995)008<2213:ISOCSS>2.0.CO;2 `_ * Briegleb, B. and Ramanathan, V. (1982), Spectral and Diurnal Variations in Clear Sky Planetary Albedo. J. Appl. Meteor., 21, - 1160–1171, `doi:10.1175/1520-0450(1982)021<1160:SADVIC>2.0.CO;2 + 1160-1171, `doi:10.1175/1520-0450(1982)021<1160:SADVIC>2.0.CO;2 `_ * Liu, J. , Zhang, Z. , Inoue, J. and Horton, R. M. (2007), Evaluation of snow/ice albedo parameterizations and their impacts @@ -302,9 +302,9 @@ This file sets the radiation options. It contains one namelist called :nml:lst:` Robert M. Haberle. Astrobiology. Jan 2012. ahead of print `doi:10.1089/ast.2011.0668 `_ - * Martin Turbet, Jérémy Leconte, Franck Selsis, Emeline Bolmont, - François Forget, Ignasi Ribas, Sean N. Raymond and Guillem - Anglada-Escudé (2016), The habitability of Proxima Centauri + * Martin Turbet, J|eacute|r|eacute|my Leconte, Franck Selsis, Emeline Bolmont, + Fran|ccedil|ois Forget, Ignasi Ribas, Sean N. Raymond and Guillem + Anglada-Escud|eacute| (2016), The habitability of Proxima Centauri b - II. Possible climates and observability, A&A, 596, A112, `doi:10.1051/0004-6361/201629577 `_ diff --git a/doc/source/namelists/jules_rivers.nml.rst b/doc/source/namelists/jules_rivers.nml.rst index 5de34faa..f5c5cc0f 100644 --- a/doc/source/namelists/jules_rivers.nml.rst +++ b/doc/source/namelists/jules_rivers.nml.rst @@ -87,7 +87,7 @@ River routing introduces two more grids to a JULES run: the river routing input :suggested: 1 (spatial resolution coarser than 20 km gridcells), ~10 (high-resolution) The threshold drainage area (specified in number of cells) draining to a gridbox, above which the grid cell is considered to be a river point (see a_T in Bell et al. 2007:541). - + Remaining points are treated as land (drainage area = 0) or sea (drainage area < 0). See Bell et al. (2007). @@ -216,7 +216,7 @@ River routing introduces two more grids to a JULES run: the river routing input * Dadson S.J. et al. (2011) Evaluation of a grid-based river flow model configured for use in a regional climate model. Journal of Hydrology. 411 238-250 * Falloon, P.D. et al (2007) New global river routing scheme in the Unified Model. Hadley Centre Technical Note 72, available from `the Met Office Library `_. * Jones R., Dadson, S. and Bell, V.A. (2007) Report on European grid-based river-flow modelling for application to Regional Climate Models. Met Office Hadley Centre deliverable report. - * Oki, T. and Sud, Y.C. (1998) Design of Total Runoff Integrating Pathways (TRIP)—A Global River Channel Network. Earth Interactions, 2: 1-37. + * Oki, T. and Sud, Y.C. (1998) Design of Total Runoff Integrating Pathways (TRIP)--A Global River Channel Network. Earth Interactions, 2: 1-37. * Oki, T., et al (1999) Assessment of annual runoff from land surface models using Total Runoff Integrating Pathways (TRIP). Journal of the Meteorological Society of Japan. 77 235-255 @@ -330,7 +330,7 @@ River routing introduces two more grids to a JULES run: the river routing input :type: real :default: none - :suggested: 0.08 (for "several drainages in western Washington State, USA", Cragun 2005) + :suggested: 0.08 (for "several drainages in western Washington State, USA", Cragun 2005) Coefficient in the allometry for bankfull flow (see Sen 2018:eqn3.33). @@ -339,7 +339,7 @@ River routing introduces two more grids to a JULES run: the river routing input :type: real :default: none - :suggested: 0.95 (for "several drainages in western Washington State, USA", Cragun 2005) + :suggested: 0.95 (for "several drainages in western Washington State, USA", Cragun 2005) Exponent in the allometry for bankfull flow (see Sen 2018:eqn3.33). diff --git a/doc/source/namelists/jules_snow.nml.rst b/doc/source/namelists/jules_snow.nml.rst index f842fb31..1275d2aa 100644 --- a/doc/source/namelists/jules_snow.nml.rst +++ b/doc/source/namelists/jules_snow.nml.rst @@ -1,11 +1,9 @@ ``jules_snow.nml`` ================== - This file sets the snow options and parameters. It contains one namelist called :nml:lst:`JULES_SNOW`. - ``JULES_SNOW`` namelist members ------------------------------- @@ -177,17 +175,17 @@ HCTN30 refers to Hadley Centre technical note 30, available from `the Met Office When: :nml:mem:`JULES_RADIATION::l_snow_albedo` = TRUE - These parameters are used as limits at all snow-covered - grid points. + These parameters are used as limits at all snow-covered + grid points. :nml:mem:`JULES_RADIATION::l_embedded_snow` = TRUE - These parameters are not used. + These parameters are not used. :nml:mem:`JULES_SURFACE::l_elev_land_ice` = TRUE - Irrespective of whether either of the two previous options - are selected, these parameters are used to adjust the albedo - of dense snow to a value more appropriate for firn. See - also :nml:mem:`aicemax`. + Irrespective of whether either of the two previous options + are selected, these parameters are used to adjust the albedo + of dense snow to a value more appropriate for firn. See + also :nml:mem:`aicemax`. .. nml:member:: aicemax @@ -348,8 +346,7 @@ HCTN30 refers to Hadley Centre technical note 30, available from `the Met Office :type: real :default: 0.265 - Thermal conductivity of lying snow (W m\ :sup:`-1` K\ - :sup:`-1`). + Thermal conductivity of lying snow (W m\ :sup:`-1` K\ :sup:`-1`). This value is used for all snow if :nml:mem:`nsmax` = 0, but only for thin snow if :nml:mem:`nsmax` > 0. See HCTN30 Eq.42. for its @@ -473,7 +470,7 @@ HCTN30 refers to Hadley Centre technical note 30, available from `the Met Office TRUE Pass rainfall and melting from the canopy to the snowpack as - infiltration. + infiltration. FALSE No effect. @@ -539,13 +536,13 @@ HCTN30 refers to Hadley Centre technical note 30, available from `the Met Office Scheme used to calculate the rate of growth of snow grains. 0. Invokes the original scheme based on :ref:`Marshall - (1989)`, with no dependence of the rate of - growth of small grains on the temperature. + (1989)`, with no dependence of the rate of + growth of small grains on the temperature. 1. Invokes the scheme for growth of snow grains proposed by - :ref:`Taillandier et al. (2007)` for - equitemperature metamorphism. Growth is significantly - slower than the default scheme at low temperatures. + :ref:`Taillandier et al. (2007)` for + equitemperature metamorphism. Growth is significantly + slower than the default scheme at low temperatures. .. nml:member:: i_relayer_opt @@ -559,11 +556,11 @@ HCTN30 refers to Hadley Centre technical note 30, available from `the Met Office Only used if :nml:mem:`nsmax` > 0. 0. Invokes the original scheme with relayering of the grain size - involving the grain size itself. + involving the grain size itself. 1. Relayering is done using the inverse of the grain size. This - is more consistent with conserving the specific surface area - of snow, though full conservation would require mass - weighting to be invoked during regridding. + is more consistent with conserving the specific surface area + of snow, though full conservation would require mass + weighting to be invoked during regridding. .. nml:member:: i_basal_melting_opt @@ -582,12 +579,9 @@ HCTN30 refers to Hadley Centre technical note 30, available from `the Met Office 0. Default: Basal melting is omitted. 1. Basal melting takes place instantaneously if the temperature - of the first soil layer is above freezing, until the snow is - removed or the temperature of soil layer is reduced to - freezing. - - - + of the first soil layer is above freezing, until the snow is + removed or the temperature of soil layer is reduced to + freezing. Example of the evolution of snow layer thickness @@ -616,8 +610,6 @@ The table below gives an example of how the number and thickness of snow layers | | | | dealt with by increasing the thickness in this bottom layer. | +--------------------+-----------+----------------------+---------------------------------------------------------------------------------+ - - .. |mu| unicode:: μ .. u .. _References_snow: @@ -628,21 +620,19 @@ The table below gives an example of how the number and thickness of snow layers * Calonne, N., Flin, F., Morin, S., Lesaffre, B., du Roscoat, S. Rolland, and Geindreau, C. (2011). Numerical and experimental investigations of the effective thermal conductivity of - snow, Geophys. Res. Lett., 38, L23501, - https://doi.org/10.1029/2011GL049234. + snow, Geophys. Res. Lett., 38, L23501, https://doi.org/10.1029/2011GL049234 * Dutra, E., Balsamo, G., Viterbo, P., Miranda, P. M., Beljaars, A., Schar, C., and Elder, K. (2010). An improved snow scheme for the ECMWF land surface model: Description and offline validation, J. Hydrometeorol., - 11, 899–916, https://doi.org/10.1175/2010JHM1249.1. + 11, 899-916, https://doi.org/10.1175/2010JHM1249.1 * Marshall, S.E. (1989). A physical parameterization of snow albedo for use in climate models. NCAR Cooperative Thesis 123. Boulder, CO : - National Center for Atmospheric - Research. https://atmos.washington.edu/~sgw/PAPERS/1989_Marshall.pdf + National Center for Atmospheric Research. + https://atmos.washington.edu/~sgw/PAPERS/1989_Marshall.pdf * Taillandier, A.-S., F. Domine, W. R. Simpson, M. Sturm, and T. A. Douglas (2007). Rate of decrease of the specific surface area of dry snow: Isothermal and temperature gradient - conditions, J. Geophys. Res., 112, F03003, - https://doi.org/10.1029/2006JF000514. + conditions, J. Geophys. Res., 112, F03003, https://doi.org/10.1029/2006JF000514 * Yen, Y.-C. (1981). Review of thermal properties of snow, ice and sea ice. Cold Regions Research and Engineering Laboratory (CRREL) Report - 81-10. https://hdl.handle.net/11681/9469 + 81-10, https://hdl.handle.net/11681/9469 diff --git a/doc/source/namelists/jules_soil.nml.rst b/doc/source/namelists/jules_soil.nml.rst index e07ceaf0..28734f9d 100644 --- a/doc/source/namelists/jules_soil.nml.rst +++ b/doc/source/namelists/jules_soil.nml.rst @@ -1,11 +1,9 @@ ``jules_soil.nml`` ================== - This file sets the soil options and parameters. It contains one namelist called :nml:lst:`JULES_SOIL`. - ``JULES_SOIL`` namelist members ------------------------------- @@ -20,11 +18,11 @@ This file sets the soil options and parameters. It contains one namelist called Number of soil layers. A value of 4 is often used, with soil layer depths that have been tuned using this. - + .. warning:: If :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0, ``sm_levels >= 3`` is required. - + .. nml:member:: l_vg_soil :type: logical @@ -40,7 +38,7 @@ This file sets the soil options and parameters. It contains one namelist called .. seealso:: References: - + * Brooks, R.H. and A.T. Corey, 1964, Hydraulic properties of porous media. Colorado State University Hydrology Papers 3. * van Genuchten, M.T., 1980, A Closed-form Equation for Predicting the Hydraulic Conductivity of Unsaturated Soils. Soil Science Society of America Journal, 44:892-898. @@ -51,8 +49,8 @@ This file sets the soil options and parameters. It contains one namelist called :default: F Switch to calculate vertical gradient of soil suction with the assumption of linearity only for fractional saturation (consistent with the calculation of hydraulic conductivity). - - + + .. nml:member:: l_soil_sat_down :type: logical @@ -101,10 +99,10 @@ This file sets the soil options and parameters. It contains one namelist called .. seealso:: References: - + * Chadburn et al (2015). An improved representation of physical permafrost dynamics in a global land-surface scheme. Geoscientific Model Development * Dharssi et al (2009). New soil physical properties implemented in the Unified Model at PS18. Met Office Technical note 528 - * Johansen (1975). Thermal conductivity of soils. PhD thesis. University of Trondheim, Norway + * Johansen (1975). Thermal conductivity of soils. PhD thesis. University of Trondheim, Norway * Peters-Lidard et al (1998). The effect of soil thermal conductivity parameterisation on surface energy fluxes and temperatures. J. Atmos. Sci. 55:1209-1224 @@ -114,15 +112,15 @@ This file sets the soil options and parameters. It contains one namelist called :default: F Switch for using a thermal bedrock column beneath the soil column. The bedrock has no hydrological processes - diffusion of heat is the only process represented. - + Properties of the bedrock can be set using :nml:mem:`ns_deep`, :nml:mem:`hcapdeep`, :nml:mem:`hcondeep` and :nml:mem:`dzdeep`. - + TRUE An additional bedrock column is used below the soil column. - + FALSE No effect. - + .. seealso:: For full details see Chadburn et al. (2015) @@ -213,7 +211,7 @@ This file sets the soil options and parameters. It contains one namelist called :type: real :default: None - Depth of the tiled solid-ice bedrock-type layer used underneath individual ice tiles if :nml:mem:`JULES_SURFACE::l_elev_land_ice` is TRUE. + Depth of the tiled solid-ice bedrock-type layer used underneath individual ice tiles if :nml:mem:`JULES_SURFACE::l_elev_land_ice` is TRUE. Effectively this sets the amount of thermal buffering each surface tile has to heat fluxes penetrating through the snowpack. .. nml:member:: l_tile_soil @@ -226,7 +224,7 @@ This file sets the soil options and parameters. It contains one namelist called See also :nml:mem:`l_broadcast_ancils` and :nml:mem:`JULES_INITIAL::l_broadcast_soilt`. .. note:: - Setting :nml:mem:`l_tile_soil` = TRUE means a separate soil tile exists for each surface tile (rather than all surface tiles using the same, single soil tile). This also alters the names of many of the soil prognostic and ancillary variables that are used (see elsewhere), with the suffix "_soilt'' being added to indicate the presence of soil tiling. The switches :nml:mem:`l_broadcast_ancils` and :nml:mem:`JULES_INITIAL::l_broadcast_soilt` allow soil tiling to be used with input files that do not contain soil tile information. Setting :nml:mem:`l_broadcast_ancils` = TRUE means that a soil ancillary file that does not contain soil tiles can be used in a tiled run. Setting :nml:mem:`JULES_INITIAL::l_broadcast_soilt` = TRUE means an initital state file that does not contain soil tiles can be used to initialise a run with soil tiles. + Setting :nml:mem:`l_tile_soil` = TRUE means a separate soil tile exists for each surface tile (rather than all surface tiles using the same, single soil tile). This also alters the names of many of the soil prognostic and ancillary variables that are used (see elsewhere), with the suffix "_soilt'' being added to indicate the presence of soil tiling. The switches :nml:mem:`l_broadcast_ancils` and :nml:mem:`JULES_INITIAL::l_broadcast_soilt` allow soil tiling to be used with input files that do not contain soil tile information. Setting :nml:mem:`l_broadcast_ancils` = TRUE means that a soil ancillary file that does not contain soil tiles can be used in a tiled run. Setting :nml:mem:`JULES_INITIAL::l_broadcast_soilt` = TRUE means an initial state file that does not contain soil tiles can be used to initialise a run with soil tiles. .. nml:member:: l_broadcast_ancils diff --git a/doc/source/namelists/jules_soil_biogeochem.nml.rst b/doc/source/namelists/jules_soil_biogeochem.nml.rst index a138b998..7581c716 100644 --- a/doc/source/namelists/jules_soil_biogeochem.nml.rst +++ b/doc/source/namelists/jules_soil_biogeochem.nml.rst @@ -1,7 +1,6 @@ ``jules_soil_biogeochem.nml`` ============================= - This file sets options and parameters for soil biogeochemistry. If using the single-pool or 4-pool soil models, all soil parameters are read from this file. @@ -9,7 +8,6 @@ If using the single-pool or 4-pool soil models, all soil parameters are read fro If using the ECOSSE soil model, most soil parameters are read from a separate file (:ref:`jules-soil-ecosse-namelist`). - ``JULES_SOIL_BIOGEOCHEM`` namelist members ------------------------------------------ @@ -98,7 +96,7 @@ If using the ECOSSE soil model, most soil parameters are read from a separate fi * Jenkinson, D.S., 1990. The turnover of organic carbon and nitrogen in soil. Philosophical Transactions of the Royal Society of London. Series B: Biological Sciences, 329(1255), pp.361-368. (https://doi.org/10.1098/rstb.1990.0177) - * Clark, D. B., Mercado, L. M., Sitch, S., Jones, C. D., Gedney, N., Best, M. J., Pryor, M., Rooney, G. G., Essery, R. L. H., Blyth, E., Boucher, O., Harding, R. J., Huntingford, C., and Cox, P. M.: The Joint UK Land Environment Simulator (JULES), model description – Part 2: Carbon fluxes and vegetation dynamics, Geosci. Model Dev., 4, 701–722, (https://doi.org/10.5194/gmd-4-701-2011), 2011. + * Clark, D. B., Mercado, L. M., Sitch, S., Jones, C. D., Gedney, N., Best, M. J., Pryor, M., Rooney, G. G., Essery, R. L. H., Blyth, E., Boucher, O., Harding, R. J., Huntingford, C., and Cox, P. M.: The Joint UK Land Environment Simulator (JULES), model description - Part 2: Carbon fluxes and vegetation dynamics, Geosci. Model Dev., 4, 701-722, (https://doi.org/10.5194/gmd-4-701-2011), 2011. .. nml:member:: l_soil_resp_lev2 @@ -140,7 +138,7 @@ If using the ECOSSE soil model, most soil parameters are read from a separate fi References: * Burke, E. J., Chadburn, S. E., and Ekici, A.: A vertical representation of soil carbon in the JULES land surface scheme (vn4.3_permafrost) with a focus on permafrost regions, Geosci. Model Dev., 10, 959-975, doi:10.5194/gmd-10-959-2017, 2017. - + .. nml:member:: l_label_frac_cs :type: logical @@ -157,7 +155,7 @@ If using the ECOSSE soil model, most soil parameters are read from a separate fi .. seealso:: References: - * Burke, E. J., Chadburn, S. E., and Ekici, A.: A vertical representation of soil carbon in the JULES land surface scheme (vn4.3_permafrost) with a focus on permafrost regions, Geosci. Model Dev., 10, 959-975, doi:10.5194/gmd-10-959-2017, 2017. + * Burke, E. J., Chadburn, S. E., and Ekici, A.: A vertical representation of soil carbon in the JULES land surface scheme (vn4.3_permafrost) with a focus on permafrost regions, Geosci. Model Dev., 10, 959-975, doi:10.5194/gmd-10-959-2017, 2017. .. nml:member:: kaps_4pool @@ -212,7 +210,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 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. + 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): @@ -304,8 +302,8 @@ If using the ECOSSE soil model, most soil parameters are read from a separate fi .. note:: In the UM the recommended value depends on :nml:mem:`JULES_VEGETATION::l_triffid` as follows: - | :nml:mem:`JULES_VEGETATION::l_triffid` = FALSE, :nml:mem:`const_ch4_cs` = 5.41e-12 - | :nml:mem:`JULES_VEGETATION::l_triffid` = TRUE, :nml:mem:`const_ch4_cs` = 5.41e-10 + | :nml:mem:`JULES_VEGETATION::l_triffid` = FALSE, :nml:mem:`const_ch4_cs` = 5.41e-12 + | :nml:mem:`JULES_VEGETATION::l_triffid` = TRUE, :nml:mem:`const_ch4_cs` = 5.41e-10 .. nml:member:: q10_ch4_cs @@ -437,7 +435,7 @@ If using the ECOSSE soil model, most soil parameters are read from a separate fi Reference for microbial methane scheme: * Chadburn, S. E. et al (2020), - Modeled Microbial Dynamics Explain the Apparent Temperature Sensitivity + Modeled Microbial Dynamics Explain the Apparent Temperature Sensitivity of Wetland Methane Emissions. Global Biogeochemical Cycles, 34: e2020GB006678. `https://doi.org/10.1029/2020GB006678 `_ diff --git a/doc/source/namelists/jules_soil_ecosse.nml.rst b/doc/source/namelists/jules_soil_ecosse.nml.rst index 96e77bdb..fcb72399 100644 --- a/doc/source/namelists/jules_soil_ecosse.nml.rst +++ b/doc/source/namelists/jules_soil_ecosse.nml.rst @@ -15,7 +15,7 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist * Smith et al., 2010, Estimating changes in Scottish soil carbon stocks using ECOSSE. I. Model description and uncertainties, Climate Research, 45: 179-192. (https://doi.org/10.3354/cr00899). - * Clark, D. B., Mercado, L. M., Sitch, S., Jones, C. D., Gedney, N., Best, M. J., Pryor, M., Rooney, G. G., Essery, R. L. H., Blyth, E., Boucher, O., Harding, R. J., Huntingford, C., and Cox, P. M.: The Joint UK Land Environment Simulator (JULES), model description – Part 2: Carbon fluxes and vegetation dynamics, Geosci. Model Dev., 4, 701–722, (https://doi.org/10.5194/gmd-4-701-2011), 2011. + * Clark, D. B., Mercado, L. M., Sitch, S., Jones, C. D., Gedney, N., Best, M. J., Pryor, M., Rooney, G. G., Essery, R. L. H., Blyth, E., Boucher, O., Harding, R. J., Huntingford, C., and Cox, P. M.: The Joint UK Land Environment Simulator (JULES), model description - Part 2: Carbon fluxes and vegetation dynamics, Geosci. Model Dev., 4, 701-722, (https://doi.org/10.5194/gmd-4-701-2011), 2011. ``JULES_SOIL_ECOSSE`` namelist members @@ -30,7 +30,7 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist :default: T Switch to include soil nitrogen in ECOSSE. - + TRUE Model soil carbon and nitrogen. @@ -44,7 +44,7 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist :default: T Switch to match ECOSSE soil C and N layers to those for soil moisture. - + TRUE Use the same layering as for soil moisture. The number of soil carbon layers will equal :nml:mem:`JULES_SOIL::sm_levels`, with layer thicknesses given by :nml:mem:`JULES_SOIL::dzsoil_io`. @@ -85,14 +85,14 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist :default: T Switch controlling the averaging of the physical driving variables that are input to ECOSSE (e.g. soil temperature). - + TRUE Average the driving variables over the ECOSSE timestep length. FALSE Use instantaneous values of the driving variables at the time when ECOSSE is called. - + .. nml:member:: plant_input_profile :type: INTEGER @@ -100,7 +100,7 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist :default: 1 Switch for the vertical distribution of litterfall inputs of C and N to the soil. - + Possible values are: 1. | Fraction :nml:mem:`pi_sfc_frac` of inputs are distributed uniformly in a surface layer of depth :nml:mem:`pi_sfc_depth`, the remainder are distributed according to the distribution of roots. @@ -193,7 +193,7 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist Constants in the 4-pool from of the decomposition temperature modifier (:nml:mem:`temp_modifier` = 2). - Note that these default values are also those harwired in the code for use with the 4-pool model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2, :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_q10` = F ). + Note that these default values are also those hardwired in the code for use with the 4-pool model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2, :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_q10` = F ). @@ -212,7 +212,7 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist Minimum allowed value of the water rate modifier for decomposition when the Clark et al. (2011) form is used (:nml:mem:`water_modifier` = 1). - Note that this default value is also that harwired in the code for use with the 4-pool model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2). + Note that this default value is also that hardwired in the code for use with the 4-pool model (:nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2). .. nml:group:: Parameters for ECOSSE that are only used if soil N is included (:nml:mem:`l_soil_n` = TRUE). @@ -224,7 +224,7 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist :default: T Switch controlling how lack of nitrogen affects soil decomposition. - + TRUE Reduce the decomposition rate. @@ -238,9 +238,9 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist :permitted: 0 <= depo_nit_frac <= 1 :default: 1.0 - The fraction of nitrogen deposition that is aded to the soil nitrate pool. The complement is aded to the ammonium pool. + The fraction of nitrogen deposition that is added to the soil nitrate pool. The complement is added to the ammonium pool. + - .. nml:member:: bacteria_min_frac :type: REAL @@ -291,7 +291,7 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist The C:N ratio of soil fungi. - + .. nml:member:: depth_nitrif :type: REAL @@ -342,7 +342,7 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist Fraction of nitrification lost as gas through full nitrification. - + .. nml:member:: nitrif_frac_no :type: REAL @@ -366,7 +366,7 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist :default: 0.005 Factor in denitrification calculation to convert flux of CO\ :sub:`2` into a representation of biological activity (m\ :sup:`2` kg\ :sup:`-1`). - + .. nml:member:: denit_frac_n2_fc @@ -375,7 +375,7 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist :default: 0.55 Proportion of denitrified N that becomes N\ :sub:`2` when soil moisture is at field capacity. - + .. nml:member:: denit_nitrate_equal @@ -383,15 +383,15 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist :default: 0.4 Amount of N in soil nitrate at which denitrified N is released as equal amounts of N\ :sub:`2` and N\ :sub:`2`O (kg m\ :sup:`-3`). - + .. nml:member:: denit_water_coeff :type: REAL(3) - :default: 0.62, 0.38, 1.74 + :default: 0.62, 0.38, 1.74 Constants describing water modifier for denitrification. - + .. nml:member:: amm_leach_min @@ -399,7 +399,7 @@ This file sets options and parameters for the ECOSSE model of soil biogeochemist :default: 0.02 Minimum allowed amount of N in soil ammonium after leaching (kg m\ :sup:`-3`). - + .. nml:member:: n_inorg_max_conc diff --git a/doc/source/namelists/jules_surface.nml.rst b/doc/source/namelists/jules_surface.nml.rst index bb795534..d3d4be35 100644 --- a/doc/source/namelists/jules_surface.nml.rst +++ b/doc/source/namelists/jules_surface.nml.rst @@ -1,11 +1,9 @@ ``jules_surface.nml`` ===================== - This file sets the surface options. It contains one namelist called :nml:lst:`JULES_SURFACE`. - ``JULES_SURFACE`` namelist members ---------------------------------- @@ -204,9 +202,9 @@ This file sets the surface options. It contains one namelist called :nml:lst:`JU but each tile has an independent single layer bedrock-type solid ice boundary condition under the snowpack. In addition, when selected, dense snowpacks on elevated ice gridboxes are parameterised to behave more like firn in two ways: - 1) The meltwater-holding capacity of snow layers reduces as a linear function of their density, becoming zero + #. The meltwater-holding capacity of snow layers reduces as a linear function of their density, becoming zero above the pore-closure density of 850 kg/m^2 so as to restrict retention of melt within the snowpack. - 2) Where the top few centimetres of the pack has a density appropriate to firn/bare ice + #. Where the top few centimetres of the pack has a density appropriate to firn/bare ice and the grain-size physics otherwise used for snow albedo become less appropriate, surface albedo becomes a function of density, tending towards that of bare ice as density increases (see :nml:mem:`JULES_SNOW::rho_firn_albedo`, :nml:mem:`JULES_SNOW::amax`, :nml:mem:`JULES_SNOW::aicemax`). @@ -244,7 +242,7 @@ This file sets the surface options. It contains one namelist called :nml:lst:`JU switches from stable to unstable, due to the low turbulence determined by the stable buoyancy flux. With the interactive buoyancy flux option (l_mo_buoyancy_flux = true) the surface energy balance and buoyancy flux are calculated within the iterative calculation for the Monin-Obukhov similarity theory for the surface exchange - coefficients. On occations when the stability is around neutral it is possible that the iterative calculation does not converge. In this case the larger of the last two calculated transfer coefficients is then used to prevent + coefficients. On occasions when the stability is around neutral it is possible that the iterative calculation does not converge. In this case the larger of the last two calculated transfer coefficients is then used to prevent any unrealistic surface temperatures. .. nml:group:: Surface parameters diff --git a/doc/source/namelists/jules_surface_types.nml.rst b/doc/source/namelists/jules_surface_types.nml.rst index 7831fc7c..d23cc7f5 100644 --- a/doc/source/namelists/jules_surface_types.nml.rst +++ b/doc/source/namelists/jules_surface_types.nml.rst @@ -1,5 +1,6 @@ ``jules_surface_types.nml`` =========================== + .. _top_jules_surface_types: This file configures the surface types used by JULES. It contains one @@ -21,9 +22,9 @@ and removed in the GUI window as described in the table below. To: ====== ================================================= .. note:: Please be aware that while the surface type IDs have been - made available and are used to check the surface type - configuration at runtime, they are not yet used by the JULES - I/O. + made available and are used to check the surface type + configuration at runtime, they are not yet used by the JULES + I/O. ``JULES_SURFACE_TYPES`` namelist members ---------------------------------------- @@ -71,105 +72,109 @@ and removed in the GUI window as described in the table below. To: A negative value, when permitted, indicates that the surface type is not in use. - .. nml:member:: urban - - :type: integer - :permitted: -1, npft+1:ntype - :default: -32768 +.. nml:member:: urban - Index of the urban surface type (#6). + :type: integer + :permitted: -1, npft+1:ntype + :default: -32768 - Can only be used if :nml:mem:`JULES_SURFACE::l_urban2t` = FALSE. + Index of the urban surface type (#6). + Can only be used if :nml:mem:`JULES_SURFACE::l_urban2t` = FALSE. - .. nml:member:: lake - :type: integer - :permitted: npft+1:ntype - :default: -32768 +.. nml:member:: lake - Index of the lake surface type (#7). + :type: integer + :permitted: npft+1:ntype + :default: -32768 + Index of the lake surface type (#7). - .. nml:member:: soil - :type: integer - :permitted: npft+1:ntype - :default: -32768 +.. nml:member:: soil - Index of the soil surface type (#8). + :type: integer + :permitted: npft+1:ntype + :default: -32768 - .. note:: A soil surface type must be given (although the fraction may be set to zero). + Index of the soil surface type (#8). + .. note:: A soil surface type must be given (although the fraction may be set to zero). - .. nml:member:: ice - :type: integer - :permitted: npft+1:ntype - :default: -32768 +.. nml:member:: ice - Index of the ice surface type (#9). + :type: integer + :permitted: npft+1:ntype + :default: -32768 - .. note:: In the UM the ice surface type must be specified (although the fraction may be set to zero). + Index of the ice surface type (#9). + .. note:: In the UM the ice surface type must be specified (although the fraction may be set to zero). - .. nml:group:: Multiple ice tiles allowed to exist in an ice gridbox - These surface types can only be used when multiple ice tiles are - allowed in a gridbox i.e. when - :nml:mem:`JULES_SURFACE::l_elev_land_ice` = TRUE. +.. nml:group:: Multiple ice tiles allowed to exist in an ice gridbox - .. nml:member:: elev_ice + These surface types can only be used when multiple ice tiles are + allowed in a gridbox i.e. when + :nml:mem:`JULES_SURFACE::l_elev_land_ice` = TRUE. - :type: integer - :permitted: -1,npft+1:ntype - :default: -32768 +.. nml:member:: elev_ice - Indices of the elevated ice types (#901-925). + :type: integer + :permitted: -1,npft+1:ntype + :default: -32768 - Must be grouped together with values ``npft < elev_ice <= - ntype`` OR ``elev_ice = -1`` to indicate they are not used - (i.e. all elevated rock instead). + Indices of the elevated ice types (#901-925). - .. nml:member:: elev_rock + Must be grouped together with values ``npft < elev_ice <= + ntype`` OR ``elev_ice = -1`` to indicate they are not used + (i.e. all elevated rock instead). - :type: integer - :permitted: -1,npft+1:ntype - :default: -32768 +.. nml:member:: elev_rock - Indices of the elevated non-glaciated bedrock types - (#926-950). + :type: integer + :permitted: -1,npft+1:ntype + :default: -32768 - Must be grouped together, with values ``npft < elev_rock <= - ntype`` OR ``elev_rock = -1`` to indicate they are not used - (i.e. all elevated ice instead). + Indices of the elevated non-glaciated bedrock types + (#926-950). + Must be grouped together, with values ``npft < elev_rock <= + ntype`` OR ``elev_rock = -1`` to indicate they are not used + (i.e. all elevated ice instead). - .. nml:group:: Two-tile urban schemes including MORUSES - These surface types can only be used when :nml:mem:`JULES_SURFACE::l_urban2t` = TRUE. +.. nml:group:: Two-tile urban schemes including MORUSES - .. nml:member:: urban_canyon + These surface types can only be used when :nml:mem:`JULES_SURFACE::l_urban2t` = TRUE. - :type: integer - :permitted: npft+1:ntype - :default: -32768 +.. nml:member:: urban_canyon - Index of the urban canyon surface type (#601). + :type: integer + :permitted: npft+1:ntype + :default: -32768 + Index of the urban canyon surface type (#601). - .. nml:member:: urban_roof - :type: integer - :permitted: npft+1:ntype - :default: -32768 +.. nml:member:: urban_roof - Index of the urban roof surface type (#602). + :type: integer + :permitted: npft+1:ntype + :default: -32768 + Index of the urban roof surface type (#602). - .. note:: + .. note:: - When giving urban fraction data (see :nml:lst:`JULES_FRAC`), total *urban* fraction may be given instead of the separate canyon and roof fractions by entering it under the canyon fraction. When initialising if the roof fraction is zero, the canyon fraction will be interpreted as the total *urban* fraction and be partitioned according to the canyon fraction (W/R, see :nml:lst:`URBAN_PROPERTIES`). + When giving urban fraction data (see :nml:lst:`JULES_FRAC`), + total *urban* fraction may be given instead of the separate canyon and + roof fractions by entering it under the canyon fraction. When initialising + if the roof fraction is zero, the canyon fraction will be interpreted as + the total *urban* fraction and be partitioned according to the canyon + fraction (W/R, see :nml:lst:`URBAN_PROPERTIES`). .. nml:group:: Surface types with ``compulsory=false`` @@ -179,148 +184,148 @@ and removed in the GUI window as described in the table below. To: surface type if it is not required (see explanation at the :ref:`top` of this page). - .. nml:member:: usr_type +.. nml:member:: usr_type - :type: integer - :permitted: 1:ntype - :default: -32768 + :type: integer + :permitted: 1:ntype + :default: -32768 - Index of user specified surface type (#10-99). + Index of user specified surface type (#10-99). - A user surface type can be used when experimenting with new - surface configurations without a code change. These can be - either vegetated or non-vegetated and are used solely to assign an - ID number. + A user surface type can be used when experimenting with new + surface configurations without a code change. These can be + either vegetated or non-vegetated and are used solely to assign an + ID number. - .. nml:group:: Vegetated surface types +.. nml:group:: Vegetated surface types - A negative value, when permitted, indicates that the surface - type is not in use. + A negative value, when permitted, indicates that the surface + type is not in use. - .. nml:member:: brd_leaf +.. nml:member:: brd_leaf - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of the original broadleaf PFT surface type (#1). + Index of the original broadleaf PFT surface type (#1). - .. nml:member:: brd_leaf_dec +.. nml:member:: brd_leaf_dec - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of broadleaf (decidous) PFT surface type (#101) + Index of broadleaf (deciduous) PFT surface type (#101) - .. nml:member:: brd_leaf_eg_trop +.. nml:member:: brd_leaf_eg_trop - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of broadleaf (evergreen tropical) PFT surface type (#102). + Index of broadleaf (evergreen tropical) PFT surface type (#102). - .. nml:member:: brd_leaf_eg_temp +.. nml:member:: brd_leaf_eg_temp - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of broadleaf (evergreen temperate) PFT surface type (#103). + Index of broadleaf (evergreen temperate) PFT surface type (#103). - .. nml:member:: ndl_leaf +.. nml:member:: ndl_leaf - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of original needleleaf PFT surface type (#2). + Index of original needleleaf PFT surface type (#2). - .. nml:member:: ndl_leaf_dec +.. nml:member:: ndl_leaf_dec - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of needleleaf (deciduous) PFT surface type (#201). + Index of needleleaf (deciduous) PFT surface type (#201). - .. nml:member:: ndl_leaf_eg +.. nml:member:: ndl_leaf_eg - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of needleleaf (evergreen) PFT surface type (#202). + Index of needleleaf (evergreen) PFT surface type (#202). - .. nml:member:: c3_grass +.. nml:member:: c3_grass - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of original C3 grass PFT surface type (#3). + Index of original C3 grass PFT surface type (#3). - .. nml:member:: c3_crop +.. nml:member:: c3_crop - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of C3 crop PFT surface type (#301). + Index of C3 crop PFT surface type (#301). - .. nml:member:: c3_pasture +.. nml:member:: c3_pasture - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of C3 pasture PFT surface type (#302). + Index of C3 pasture PFT surface type (#302). - .. nml:member:: c4_grass +.. nml:member:: c4_grass - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of original C4 grass PFT surface type (#4). + Index of original C4 grass PFT surface type (#4). - .. nml:member:: c4_crop +.. nml:member:: c4_crop - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of C4 crop PFT surface type (#401). + Index of C4 crop PFT surface type (#401). - .. nml:member:: c4_pasture +.. nml:member:: c4_pasture - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of C4 pasture PFT surface type (#402). + Index of C4 pasture PFT surface type (#402). - .. nml:member:: shrub +.. nml:member:: shrub - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of original shrub PFT surface type (#5). + Index of original shrub PFT surface type (#5). - .. nml:member:: shrub_dec +.. nml:member:: shrub_dec - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of shrub (deciduous) PFT surface type (#501). + Index of shrub (deciduous) PFT surface type (#501). - .. nml:member:: shrub_eg +.. nml:member:: shrub_eg - :type: integer - :permitted: 1:npft - :default: -32768 + :type: integer + :permitted: 1:npft + :default: -32768 - Index of shrub (evergreen) PFT surface type (#502). + Index of shrub (evergreen) PFT surface type (#502). diff --git a/doc/source/namelists/jules_vegetation.nml.rst b/doc/source/namelists/jules_vegetation.nml.rst index d257a40d..ccdf9aa2 100644 --- a/doc/source/namelists/jules_vegetation.nml.rst +++ b/doc/source/namelists/jules_vegetation.nml.rst @@ -1,7 +1,6 @@ ``jules_vegetation.nml`` ======================== - This file sets the vegetation options. It contains one namelist called :nml:lst:`JULES_VEGETATION`. @@ -18,15 +17,15 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: Switch for using trait-based physiology. TRUE - Vcmax is calculated based on observed leaf traits. Leaf - nitrogen (nmass: kgN kgLeaf\ :sup:`-1`) and leaf mass (LMA: - kgLeaf m\ :sup:`-2`) can be based on observations from the TRY - database. Vcmax (umol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is based - on linear regressions as in :ref:`Kattge et al. 2009`. Two additional - parameters are needed: vint and vsl - the intercept and slope, - respectively, that relate the leaf nitrogen to vcmax. Sigl is - replaced with LMA (sigl=LMA*Cmass, where Cmass is the - kgC kgLeaf\ :sup:`-1` and is 0.4). + Vcmax is calculated based on observed leaf traits. Leaf nitrogen + (nmass: kgN kgLeaf\ :sup:`-1`) and leaf mass (LMA: kgLeaf m\ :sup:`-2`) + can be based on observations from the TRY database. + Vcmax (umol CO\ :sub:`2` m\ :sup:`-2` s\ :sup:`-1`) is based on linear + regressions as in :ref:`Kattge et al. 2009`. + Two additional parameters are needed: vint and vsl - the intercept and + slope, respectively, that relate the leaf nitrogen to vcmax. Sigl is + replaced with LMA (sigl=LMA*Cmass, where Cmass is the kgC + kgLeaf\ :sup:`-1` and is 0.4). FALSE Vcmax is calculated based on parameters nl0 (kgN kgC\ :sup:`-1`) and neff. @@ -98,9 +97,8 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: FALSE Use the vegetation competition described in :ref:`HCTN24`. - This is hard-wired for 5 PFTs (BT, NT, C3, C4, SH, in that - order) with co-competition for grasses and trees in - ``lokta_jls.F90``. + This is hard-wired for 5 PFTs (BT, NT, C3, C4, SH, in that order) with + co-competition for grasses and trees in ``lokta_jls.F90``. .. nml:member:: l_nitrogen @@ -251,9 +249,9 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: :nml:mem:`JULES_VEGETATION::l_use_pft_psi` = T. .. note:: The option :nml:mem:`JULES_VEGETATION::fsmc_shape` = 1 is - still in development. Users should ensure that results - are as expected, and provide feedback where deficiencies - are identified. + still in development. Users should ensure that results + are as expected, and provide feedback where deficiencies + are identified. .. nml:member:: l_use_pft_psi @@ -272,14 +270,14 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: :nml:mem:`JULES_PFTPARM::fsmc_p0_io`. .. note:: Soil respiration and surface conductance of bare soil - respectively will depend on ``sm_wilt`` and ``sm_crit`` - in :nml:lst:`JULES_SOIL_PROPS`, regardless of the setting - of :nml:mem:`JULES_VEGETATION::fsmc_shape`. + respectively will depend on ``sm_wilt`` and ``sm_crit`` + in :nml:lst:`JULES_SOIL_PROPS`, regardless of the setting + of :nml:mem:`JULES_VEGETATION::fsmc_shape`. .. note:: The option :nml:mem:`JULES_VEGETATION::l_use_pft_psi` = T - is still in development. Users should ensure that results - are as expected, and provide feedback where deficiencies - are identified. + is still in development. Users should ensure that results + are as expected, and provide feedback where deficiencies + are identified. .. nml:member:: l_vegcan_soilfx @@ -407,7 +405,7 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: Allows for representation of bioenergy crops with continuous or periodic harvesting of agricultural PFTs at prescribed intervals. Requires :nml:mem:`JULES_VEGETATION::l_trif_crop` = TRUE. TRUE - Crop, pasture, and bioenergy crop areas are defined by the :nml:mem:`JULES_AGRIC::frac_agr`, :nml:mem:`JULES_AGRIC::frac_past`, :nml:mem:`JULES_AGRIC::frac_biocrop` variables respectively. Harvests are permitted from any land class and enabled for each PFT separately using the :nml:mem:`JULES_TRIFFID::harvest_type_io` variable. Harvesting may be continuous (as per the existing scheme in :nml:mem:`JULES_VEGETATION::l_trif_crop`, when :nml:mem:`JULES_TRIFFID::harvest_type_io` is 1), or performed at prescribed intervals defined using the :nml:mem:`JULES_TRIFFID::harvest_freq_io` and :nml:mem:`JULES_TRIFFID::harvest_ht_io` variables (when :nml:mem:`JULES_TRIFFID::harvest_type_io` is 2). + Crop, pasture, and bioenergy crop areas are defined by the :nml:mem:`JULES_AGRIC::frac_agr`, :nml:mem:`JULES_AGRIC::frac_past`, :nml:mem:`JULES_AGRIC::frac_biocrop` variables respectively. Harvests are permitted from any land class and enabled for each PFT separately using the :nml:mem:`JULES_TRIFFID::harvest_type_io` variable. Harvesting may be continuous (as per the existing scheme in :nml:mem:`JULES_VEGETATION::l_trif_crop`, when :nml:mem:`JULES_TRIFFID::harvest_type_io` is 1), or performed at prescribed intervals defined using the :nml:mem:`JULES_TRIFFID::harvest_freq_io` and :nml:mem:`JULES_TRIFFID::harvest_ht_io` variables (when :nml:mem:`JULES_TRIFFID::harvest_type_io` is 2). FALSE Land use classes, PFT partitioning, and harvests are as defined by the :nml:mem:`JULES_VEGETATION::l_trif_crop` switch. @@ -447,10 +445,10 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: .. note:: :nml:mem:`can_model` = 1 does not mean that there is no - vegetation canopy. It means that the surface is - represented as a single entity, rather than having - distinct surface and canopy levels for the purposes of - radiative processes. + vegetation canopy. It means that the surface is + represented as a single entity, rather than having + distinct surface and canopy levels for the purposes of + radiative processes. .. nml:member:: can_rad_mod @@ -490,15 +488,15 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: .. note:: :nml:mem:`can_rad_mod` = 1 and 6 are recommended. .. note:: When using :nml:mem:`can_rad_mod` = 4, 5 or 6 it is - recommended to use driving data that contains direct and - diffuse radiation separately rather than a constant - diffuse fraction. + recommended to use driving data that contains direct and + diffuse radiation separately rather than a constant + diffuse fraction. .. seealso:: Descriptions of option 1 can be found in - :ref:`Jogireddy et al. (2006)`, and an - application of option 4 can be found in :ref:`Mercado - et al. (2007)`. Options 1 to 5 are - described in :ref:`Clark et al (2011)`. + :ref:`Jogireddy et al. (2006)`, and an + application of option 4 can be found in :ref:`Mercado + et al. (2007)`. Options 1 to 5 are + described in :ref:`Clark et al (2011)`. .. nml:member:: ilayers @@ -532,7 +530,7 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: .. seealso:: References: - * Collatz et al., 1991, Physiological and environmental regulation of stomatal conductance, photosynthesis, and transpiration – a model that includes a laminar boundary layer, Agricultural and Forest Meteorology, https://doi.org/10.1016/0168-1923(91)90002-8. + * Collatz et al., 1991, Physiological and environmental regulation of stomatal conductance, photosynthesis, and transpiration - a model that includes a laminar boundary layer, Agricultural and Forest Meteorology, https://doi.org/10.1016/0168-1923(91)90002-8. * Collatz et al., 1992, Coupled Photosynthesis-Stomatal Conductance Model for Leaves of C\ :sub:`4` Plants, Australian Journal of Plant Physiology, https://doi.org/10.1071/PP9920519. * Farquhar et al., 1980, A biochemical model of photosynthetic CO\ :sub:`2` assimilation in leaves of C\ :sub:`3` species, Planta, https://doi.org/10.1007/BF0038623. @@ -583,7 +581,7 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: :type: real :default: 5.241e-4 - Power in sigmodial function used to get competition coefficients. + Power in sigmoidal function used to get competition coefficients. See Hadley Centre Technical Note 24, Eq.3. @@ -656,8 +654,7 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: :default: F Switch to use the Robust Ecosystem Demography (RED). - This is based on :ref:`Argles, Arthur PK, et al. - (2020)`. + This is based on :ref:`Argles, Arthur PK, et al. (2020)`. Only use if any :nml:mem:`l_triffid` = TRUE. @@ -930,7 +927,7 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: :type: real(3) :default: None - Coefficients for the ratio J\ :sub:`25`/V\ :sub:`25` (mol electrons [mol\ :sup:`-1` CO\ :sub:`2`] and (mol electrons [mol\ :sup:`-1` CO\ :sub:`2`] K\ :sup:`-1`). Replaces the use of :nml:mem:`JULES_PFTPARM::jv25_ratio_io`. + Coefficients for the ratio J\ :sub:`25`/V\ :sub:`25` (mol electrons [mol\ :sup:`-1` CO\ :sub:`2`]) and (mol electrons [mol\ :sup:`-1` CO\ :sub:`2`] K\ :sup:`-1`). Replaces the use of :nml:mem:`JULES_PFTPARM::jv25_ratio_io`. .. nml:group:: Only used with thermal acclimation of photosynthesis (:nml:mem:`photo_acclim_model` = 2 or 3). @@ -948,7 +945,7 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: :type: logical :default: F - Switch that enables sequential cropping (crop rotations). + Switch that enables sequential cropping (crop rotations). Only used if :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0 and if :nml:mem:`JULES_VEGETATION::l_prescsow` = T. @@ -965,22 +962,22 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: ``JULES_VEGETATION`` references ------------------------------- -* Argles, A. P. K., Moore, J. R., Huntingford, C., Wiltshire, A. J., - Harper, A. B., Jones, C. D., and Cox, P. M.: Robust Ecosystem Demography - (RED version 1.0): a parsimonious approach to modelling vegetation - dynamics in Earth system models, Geosci. Model Dev., 13, 4067–4089, +* Argles, A. P. K., Moore, J. R., Huntingford, C., Wiltshire, A. J., + Harper, A. B., Jones, C. D., and Cox, P. M.: Robust Ecosystem Demography + (RED version 1.0): a parsimonious approach to modelling vegetation + dynamics in Earth system models, Geosci. Model Dev., 13, 4067-4089, https://doi.org/10.5194/gmd-13-4067-2020 * Best et al., 2011, The Joint UK Land Environment Simulator (JULES), - model description – Part 1: Energy and water fluxes, Geosci. Model + model description - Part 1: Energy and water fluxes, Geosci. Model Dev., https://doi.org/10.5194/gmd-4-677-2011. * Clark et al., 2011, The Joint UK Land Environment Simulator (JULES) - model description – Part 2: Carbon fluxes and vegetation dynamics, + 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 + 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 @@ -1029,7 +1026,7 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: Jogireddy, V.: Improving the representation of radiative interception and photosynthesis for climate model applications, Tellus B, 59, - 553–565, 2007. https://doi.org/10.1111/j.1600-0889.2007.00256.x + 553-565, 2007. https://doi.org/10.1111/j.1600-0889.2007.00256.x * Mercado et al., 2018, Large sensitivity in land carbon storage due to geographical and temporal variation in the thermal response of photosynthetic capacity, New Phytologist, 218: 1462--1477, @@ -1044,9 +1041,9 @@ This file sets the vegetation options. It contains one namelist called :nml:lst: * Mathison, C , Challinor, A. J., Deva, C., Falloon, P., Garrigues, S., Moulin, S., Williams, K., and Wiltshire, A. (2019), Developing a sequential cropping capability in the JULESvn5.2 - land–surface model, Geosci. Model Dev. Discuss., + land-surface model, Geosci. Model Dev. Discuss., https://doi.org/10.5194/gmd-2019-85, in review, 2019. -* Jones et al., 2020, The impact of a simple representation of - non-structural carbohydrates on the simulated response of tropical - forests to drought, Biogeosciences, 17: 3589--3612. +* Jones et al., 2020, The impact of a simple representation of + non-structural carbohydrates on the simulated response of tropical + forests to drought, Biogeosciences, 17: 3589--3612. https://doi.org/10.5194/bg-17-3589-2020 diff --git a/doc/source/namelists/jules_water_resources.nml.rst b/doc/source/namelists/jules_water_resources.nml.rst index 70af6002..5f7d25fd 100644 --- a/doc/source/namelists/jules_water_resources.nml.rst +++ b/doc/source/namelists/jules_water_resources.nml.rst @@ -34,7 +34,7 @@ This file sets options for water resource modelling. It contains a single nameli :default: none The number of model timesteps per water resource timestep. (The main model timestep is given by :nml:mem:`JULES_TIME::timestep_len`.) - + For example, :nml:mem:`nstep_water_res` = 12 means that demands for water will be accumulated over 12 model timesteps before the water resource code is called on the 12th timestep. The water resource and river routing models must be in synchrony (i.e. be called on the same timesteps). @@ -83,7 +83,7 @@ This file sets options for water resource modelling. It contains a single nameli Switch for modelling of water for industrial use. This requires that the industrial demand is prescribed as an input to the model (see :doc:`prescribed_data.nml`). TRUE - Consider demand for water for industrial use. + Consider demand for water for industrial use. FALSE Do not consider industrial demand. diff --git a/doc/source/namelists/model_environment.nml.rst b/doc/source/namelists/model_environment.nml.rst index 5572db50..19ac64f8 100644 --- a/doc/source/namelists/model_environment.nml.rst +++ b/doc/source/namelists/model_environment.nml.rst @@ -1,7 +1,6 @@ ``model_environment.nml`` ========================= - This file sets the model environment options e.g. whether JULES is coupled to the UM or run in a standalone environment. It contains one namelist called :nml:lst:`JULES_MODEL_ENVIRONMENT`. @@ -39,7 +38,7 @@ app. = ============================== 0 JULES is being run standalone. |br| - Any options that are only available to the parent model (e.g. the UM) will be trigger ignored. + Any options that are only available to the parent model (e.g. the UM) will be trigger ignored. 1 JULES is being run coupled to the UM. |br| 2 JULES is being run coupled via OASIS (available to Rivers-only executable only). |br| Options not available to the UM are trigger-ignored. @@ -59,10 +58,8 @@ app. consolidated will appear in the following checking routines as they are completed. - * `src/control/standalone/check_unavailable_options_mod.F90 - `_ - * `src/control/um/check_jules_unavailable_options_mod.F90 - `_ + * `src/control/standalone/check_unavailable_options_mod.F90 `_ + * `src/control/um/check_unavailable_options_mod.F90 `_ .. nml:member:: lsm_id diff --git a/doc/source/namelists/model_grid.nml.rst b/doc/source/namelists/model_grid.nml.rst index 064b8d10..b5f1eeac 100644 --- a/doc/source/namelists/model_grid.nml.rst +++ b/doc/source/namelists/model_grid.nml.rst @@ -1,7 +1,6 @@ ``model_grid.nml`` ================== - This file sets up the grid configuration for the run. It contains seven namelists - :nml:lst:`JULES_INPUT_GRID`, :nml:lst:`JULES_LATLON`, :nml:lst:`JULES_LAND_FRAC`, :nml:lst:`JULES_MODEL_GRID`, :nml:lst:`JULES_NLSIZES`, :nml:lst:`JULES_SURF_HGT` and :nml:lst:`JULES_Z_LAND` Each run of JULES involves two grids: the input grid and the model grid. The input grid is the grid on which all input data are held. The model grid is the set of points on which the model is run. The model grid is the grid of points that will be processed by JULES, and is a subset of the input grid. @@ -29,7 +28,7 @@ In most cases, the model grid will be represented internally as a vector of poin :type: logical :default: F - Indicates if the input grid is 1D or 2D. + Indicates if the input grid is 1D or 2D. TRUE Variables have one grid dimension in the input file(s) - a points dimensions (e.g. a vector of land points with grid dimension "land"). @@ -45,7 +44,7 @@ In most cases, the model grid will be represented internally as a vector of poin :type: character :default: "land" - The name of the single grid dimension. + The name of the single grid dimension. .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). @@ -56,47 +55,47 @@ In most cases, the model grid will be represented internally as a vector of poin :permitted: >= 1 :default: 0 - The size of the single grid dimension. + The size of the single grid dimension. .. nml:group:: Only used when :nml:mem:`grid_is_1d` = FALSE .. nml:member:: x_dim_name - + :type: character :default: "x" - - The name of the x dimension (it may, but does not have to, coincide with :nml:mem:`JULES_RIVERS_PROPS::x_dim_name`). + + The name of the x dimension (it may, but does not have to, coincide with :nml:mem:`JULES_RIVERS_PROPS::x_dim_name`). .. note:: For ASCII files, this can be anything. For NetCDF files, it should be the name of the dimension in the input file(s). - - + + .. nml:member:: y_dim_name - + :type: character :default: "y" - + The name of the y dimension (it may, but does not have to, coincide with :nml:mem:`JULES_RIVERS_PROPS::y_dim_name`). - + .. note:: For ASCII files, this can be anything. For NetCDF files, it should be the name of the dimension in the input file(s). - - + + .. nml:member:: nx - + :type: integer :permitted: >= 1 :default: 0 - - The size of the x dimension. - - + + The size of the x dimension. + + .. nml:member:: ny - + :type: integer :permitted: >= 1 :default: 0 - - The size of the y dimension. + + The size of the y dimension. .. nml:member:: time_dim_name @@ -117,8 +116,8 @@ In most cases, the model grid will be represented internally as a vector of poin The dimension name used when variables have an additional dimension of size :nml:mem:`JULES_SURFACE_TYPES::npft`. .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). - - + + .. nml:member:: cpft_dim_name :type: character @@ -197,8 +196,8 @@ In most cases, the model grid will be represented internally as a vector of poin The dimension name used when variables have an additional dimension of size ``dim_cs1``. .. note:: For ASCII files, this can be anything. For NetCDF files, it should the name of the dimension in input file(s). - - + + .. nml:member:: bedrock_dim_name :type: character @@ -350,30 +349,30 @@ The following table summarises ancillary fields that give the location and relat .. tabularcolumns:: |p{3cm}|L| -+----------------------------+------------------------------------------------------------------------------------------+ -| Name | Description | -+============================+==========================================================================================+ -| ``latitude`` | Latitude of each point. Always required. | -| | | -+----------------------------+------------------------------------------------------------------------------------------+ -| ``longitude`` | Longitude of each point. Always required. | -| | Values in the range -180 to 360 are allowed. | -+----------------------------+------------------------------------------------------------------------------------------+ -| ``projection_x_coord`` | Values of the projection coordinate in the x direction. | -| | This is only required if :nml:mem:`l_coord_latlon` = FALSE. | -| | Note that these can have any valid unit. | -+----------------------------+------------------------------------------------------------------------------------------+ -| ``projection_y_coord`` | Values of the projection coordinate in the y direction. | -| | 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 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 | -+----------------------------+------------------------------------------------------------------------------------------+ ++----------------------------+-----------------------------------------------------------------+ +| Name | Description | ++============================+=================================================================+ +| ``latitude`` | Latitude of each point. Always required. | +| | | ++----------------------------+-----------------------------------------------------------------+ +| ``longitude`` | Longitude of each point. Always required. | +| | Values in the range -180 to 360 are allowed. | ++----------------------------+-----------------------------------------------------------------+ +| ``projection_x_coord`` | Values of the projection coordinate in the x direction. | +| | This is only required if :nml:mem:`l_coord_latlon` = FALSE. | +| | Note that these can have any valid unit. | ++----------------------------+-----------------------------------------------------------------+ +| ``projection_y_coord`` | Values of the projection coordinate in the y direction. | +| | 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 required 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,7 +386,7 @@ 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. @@ -399,7 +398,7 @@ For any input grid with more than a single location, the following are used: :type: character :default: None - The name of the file to read land fraction data from. + The name of the file to read land fraction data from. .. nml:member:: land_frac_name @@ -407,7 +406,7 @@ For any input grid with more than a single location, the following are used: :type: character :default: 'land_fraction' - The name of the variable containing the land fraction data. + The name of the variable containing the land fraction data. In the file, the variable must have no levels dimensions and no time dimension. @@ -426,7 +425,7 @@ Members of this namelist are used to select the points to be modelled from the i :type: logical :default: T - TRUE + TRUE Model land points only (from the points that are selected with other options). FALSE @@ -442,7 +441,7 @@ Members of this namelist are used to select the points to be modelled from the i :type: logical :default: F - TRUE + TRUE Force the model grid to be 1D, even if it would otherwise have been 2D. FALSE @@ -454,7 +453,7 @@ Members of this namelist are used to select the points to be modelled from the i :type: logical :default: F - TRUE + TRUE The model grid is a subset of the full input grid, specified using some valid combination of the options below. FALSE @@ -464,63 +463,63 @@ Members of this namelist are used to select the points to be modelled from the i .. nml:group:: Only used if :nml:mem:`use_subgrid` = TRUE .. nml:member:: l_bounds - + :type: logical :default: None - - TRUE + + TRUE Subset of points to model will be selected using bounds for the coordinates variables. - + FALSE Subset of points to model will be selected using a list of coordinate pairs for each point. If :nml:mem:`JULES_LATLON::l_coord_latlon` = TRUE, the coordinates used here are latitude and longitude. If :nml:mem:`JULES_LATLON::l_coord_latlon` = FALSE, the coordinates used here are the values stored in the variables projection_x_coord and projection_y_coord. - - + + .. nml:group:: Only used if :nml:mem:`l_bounds` = TRUE - + .. nml:member:: y_bounds - + :type: real(2) :default: None - + The lower and upper bounds (in that order) for the y coordinate used to select points. Assuming that the coordinate is latitude (see :nml:mem:`JULES_LATLON::l_coord_latlon`) the model grid will comprise the points where ``y_bounds(1) <= latitude <= y_bounds(2)``. - - + + .. nml:member:: x_bounds - + :type: real(2) :default: None - + The lower and upper bounds (in that order) for the x coordinate used to select points. Assuming that the coordinate is longitude (see :nml:mem:`JULES_LATLON::l_coord_latlon`) the model grid will comprise the points where ``x_bounds(1) <= longitude <= x_bounds(2)``. If the x coordinate is longitude, the values of x_bounds should lie in the range [-180, 360]. A special case is that in which the desired subgrid straddles the edge of a global input grid. For example, if the input grid has longitudes in [0, 360] and a domain of 20 degrees of longitude centred on 0degE is required, this should be indicated using ``xbounds=-10,10`` (not xbounds=360,370 because values > 360 are not recognised). In this case the JULES code recognises the cyclic nature of longitude and correctly picks up points in both hemispheres, even though -10degE is outwith the longitude values in the input grid. - - + + .. nml:group:: Only used if :nml:mem:`l_bounds` = FALSE - + .. nml:member:: npoints - + :type: integer :permitted: >= 1 :default: 0 - + The number of points to model. - - + + .. nml:member:: points_file - + :type: character :default: None - + The name of the file containing the coordinates for each point. If :nml:mem:`JULES_LATLON::l_coord_latlon` = TRUE, the coordinates used here are latitude and longitude. Each line in the file should contain the latitude and longitude (in that order) for a point. If :nml:mem:`JULES_LATLON::l_coord_latlon` = FALSE, the coordinates used here are the values stored in the variables projection_x_coord and projection_y_coord. Each line in the file should contain the value for projection_y_coord and projection_x_coord (in that order; note this is y then x) for a point. - + An error is raised and the run terminates if any coordinate pair does not match to a location in the input grid. @@ -546,11 +545,11 @@ This namelist is used to set the number of levels in the boundary layer. .. nml:namelist:: JULES_SURF_HGT -This namelist sets the elevation of each surface tile. Elevations can either be *relative to the gridbox mean* or *have constant elevation bands above sea-level*. - -If tile elevations are set relative to the gridbox mean, then the gridbox mean elevation is not required. The gridbox mean elevation is implicit in the near-surface meteorological data that are provided (higher locations will tend to be colder, have lower pressure, etc.). The elevation of each tile is used to alter the values of the air temperature and humidity (and possibly downwelling longwave, see :nml:mem:`JULES_SURFACE::l_elev_lw_down`) over that tile relative to the surface. +This namelist sets the elevation of each surface tile. Elevations can either be *relative to the gridbox mean* or *have constant elevation bands above sea-level*. + +If tile elevations are set relative to the gridbox mean, then the gridbox mean elevation is not required. The gridbox mean elevation is implicit in the near-surface meteorological data that are provided (higher locations will tend to be colder, have lower pressure, etc.). The elevation of each tile is used to alter the values of the air temperature and humidity (and possibly downwelling longwave, see :nml:mem:`JULES_SURFACE::l_elev_lw_down`) over that tile relative to the surface. -If any tile uses absolute heights (i.e. :nml:mem:`JULES_SURF_HGT::l_elev_absolute_height` has at least one element that is .true.), then the gridbox mean elevation must also be supplied. This is read in from the optional :nml:lst:`JULES_Z_LAND` namelist which is described below. The model calculates elevations relative to the gridbox mean by taking the difference between the absolute elevation and the gridbox mean. +If any tile uses absolute heights (i.e. :nml:mem:`JULES_SURF_HGT::l_elev_absolute_height` has at least one element that is .true.), then the gridbox mean elevation must also be supplied. This is read in from the optional :nml:lst:`JULES_Z_LAND` namelist which is described below. The model calculates elevations relative to the gridbox mean by taking the difference between the absolute elevation and the gridbox mean. If any tile uses absolute heights, then tile heights are set constant across a domain, regardless of whether each tile's height is specified as a relative offset or absolute. This makes it simple to set zero-offset heights for tiles that should not be considered in the elevation bands. It is no longer possible to have spatially varying tile heights if this option is used. @@ -561,7 +560,7 @@ If any tile uses absolute heights, then tile heights are set constant across a d :default: T Switch used to simplify the initialisation of tile elevation. - + .. note:: If :nml:mem:`JULES_SURFACE::l_aggregate` = TRUE, this switch is also set to TRUE. TRUE @@ -578,11 +577,11 @@ If any tile uses absolute heights, then tile heights are set constant across a d :type: logical(nsurft) :default: F - TRUE - Heights of surface tiles are absolute values above sea-level. If this option is used, then the elevation of the forcing data must also be provided (see :nml:lst:`JULES_Z_LAND` namelist below). + TRUE + Heights of surface tiles are absolute values above sea-level. If this option is used, then the elevation of the forcing data must also be provided (see :nml:lst:`JULES_Z_LAND` namelist below). FALSE - Surface tile heights are relative to the gridbox mean. + Surface tile heights are relative to the gridbox mean. .. nml:member:: use_file @@ -590,95 +589,95 @@ If any tile uses absolute heights, then tile heights are set constant across a d :type: logical :default: T - This indicates if surface tile heights relative to the gridbox mean should be read from a specified file or namelist. + This indicates if surface tile heights relative to the gridbox mean should be read from a specified file or namelist. TRUE - The variable will be read from a file if the input grid consists of more than location. - + The variable will be read from a file if the input grid consists of more than location. + FALSE - The variable will be read from a namelist if the input grid is for a single location. + The variable will be read from a namelist if the input grid is for a single location. .. nml:group:: Only used if :nml:mem:`use_file` = TRUE .. nml:member:: file - + :type: character :default: None - - The name of the file containing surface tile heights relative to the gridbox mean. - + + The name of the file containing surface tile heights relative to the gridbox mean. + .. nml:member:: surf_hgt_name - + :type: character :default: 'surf_hgt' - - The name of the variable containing surface tile heights relative to the gridbox mean. In the file, the variable must have a single levels dimension of size ``nsurft`` called :nml:mem:`JULES_INPUT_GRID::tile_dim_name`. - + + The name of the variable containing surface tile heights relative to the gridbox mean. In the file, the variable must have a single levels dimension of size ``nsurft`` called :nml:mem:`JULES_INPUT_GRID::tile_dim_name`. + .. nml:group:: Only used if :nml:mem:`use_file` = FALSE .. nml:member:: surf_hgt_io - + :type: real(nsurft) :default: None - - Surface tile heights relative to the gridbox mean for a single location. - - + + Surface tile heights relative to the gridbox mean for a single location. + + ``JULES_Z_LAND`` namelist members ----------------------------------- -This is an optional namelist and only used if any surface tile has :nml:mem:`JULES_SURF_HGT::l_elev_absolute_height` = TRUE. The namelist sets values for the elevation bands and reads the elevation of the forcing data. +This is an optional namelist and only used if any surface tile has :nml:mem:`JULES_SURF_HGT::l_elev_absolute_height` = TRUE. The namelist sets values for the elevation bands and reads the elevation of the forcing data. .. nml:namelist:: JULES_Z_LAND .. nml:member:: surf_hgt_band - + :type: real(nsurft) :default: None - Spatially invariant elevation bands for each surface tile. These may be relative to the gridbox mean or absolute elevations above sea-level depending on :nml:mem:`JULES_SURF_HGT::l_elev_absolute_height`. + Spatially invariant elevation bands for each surface tile. These may be relative to the gridbox mean or absolute elevations above sea-level depending on :nml:mem:`JULES_SURF_HGT::l_elev_absolute_height`. .. nml:member:: use_file - + :type: logical :default: T - + This indicates if the elevation of the forcing data should be read from a file or from a namelist. - + TRUE - The variable will be read from a file if the input grid consists of more than location. + The variable will be read from a file if the input grid consists of more than location. FALSE - The variable will be read from a namelist if the input grid is for a single location. + The variable will be read from a namelist if the input grid is for a single location. -.. nml:group:: Used if :nml:mem:`JULES_Z_LAND::use_file` = TRUE +.. nml:group:: Used if :nml:mem:`JULES_Z_LAND::use_file` = TRUE .. nml:member:: file - + :type: character :default: None - + The name of the file containing the elevation of the forcing data. .. nml:member:: z_land_name - + :type: character :default: 'z_land' - - The name of the variable containing the elevation of the forcing data. In the file, the variable must have no level dimensions and no time dimensions. -.. nml:group:: Used if :nml:mem:`JULES_Z_LAND::use_file` = FALSE - + The name of the variable containing the elevation of the forcing data. In the file, the variable must have no level dimensions and no time dimensions. + +.. nml:group:: Used if :nml:mem:`JULES_Z_LAND::use_file` = FALSE + .. nml:member:: z_land_io - + :type: real :default: None - - Elevation of the forcing data for a single location. + + Elevation of the forcing data for a single location. Example ~~~~~~~ -The following gives an example of how you would set up the namelists to use elevation bands above sea-level. +The following gives an example of how you would set up the namelists to use elevation bands above sea-level. :: @@ -693,7 +692,7 @@ The following gives an example of how you would set up the namelists to use elev &JULES_Z_LAND - # Set values for the elevation bands. + # Set values for the elevation bands. surf_hgt_band = 6*0.0, 1000.0, 2000.0, 3000.0, # Read the WFDEI forcing data elevation from a file @@ -718,7 +717,7 @@ A single location nx = 1, ny = 1 / - + &JULES_LATLON l_coord_latlon = T nvars = 2, @@ -726,11 +725,11 @@ A single location use_file = .false., .false., const_val = 52.168, 5.744 / - + &JULES_LAND_FRAC / &JULES_MODEL_GRID / - + &JULES_SURF_HGT zero_height = T / @@ -760,10 +759,10 @@ In this example, input files contain data on a vector of land points. The land p &JULES_INPUT_GRID grid_is_1D = T, - + npoints = 15238, grid_dim_name = "land", - + time_dim_name = "time" / @@ -785,7 +784,7 @@ In this example, input files contain data on a 2D latitude/longitude grid. The x time_dim_name = "time" / - + Specifying a subgrid using a given range of latitude and longitude ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -798,13 +797,13 @@ This can be used with either a 1D or 2D input grid. :: use_file = .true., .true., file = 'lat_lon.nc', / - + &JULES_LAND_FRAC file = 'land_mask.nc', land_frac_name = 'land_frac' / - + &JULES_MODEL_GRID land_only = F, @@ -819,7 +818,7 @@ This can be used with either a 1D or 2D input grid. :: This setup reads latitude, longitude and land fraction for each gridbox in the full input grid (1D or 2D) from the named variables in the specified files. In :nml:lst:`JULES_MODEL_GRID`, :nml:mem:`JULES_MODEL_GRID::use_subgrid` indicates that a subset of the input grid will be selected as the model grid. :nml:mem:`JULES_MODEL_GRID::l_bounds` then indicates that latitude and longitude bounds will be used to select the subgrid. :nml:mem:`JULES_MODEL_GRID::land_only` = FALSE means that sea and sea-ice points will remain in the model grid if any are selected. The model grid will then be a vector containing the selected points (those that fall within the latitude/longitude bounds), even if those points could be used to form a rectangular region. - + Specifying a subgrid using a given range of projection coordinates (not latitude and longitude) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -832,13 +831,13 @@ This can be used with either a 1D or 2D input grid. :: use_file = .true., .true., .true., .true., file = 'lat_lon.nc', / - + &JULES_LAND_FRAC file = 'land_mask.nc', land_frac_name = 'land_frac' / - + &JULES_MODEL_GRID land_only = F, @@ -881,7 +880,7 @@ This can be used with either a 1D or 2D input grid. :: npoints = 4, points_file = 'points.txt' / - + This setup reads latitude, longitude and land fraction for each gridbox in the full input grid (1D or 2D) from the named variables in the specified files. In :nml:lst:`JULES_MODEL_GRID`, :nml:mem:`JULES_MODEL_GRID::use_subgrid` indicates that a subset of the input grid will be selected as the model grid. :nml:mem:`JULES_MODEL_GRID::l_bounds` then indicates that a list of latitudes and longitudes will be used to select the subgrid. :nml:mem:`JULES_MODEL_GRID::land_only` is not given, meaning it takes its default value, TRUE. This means that any sea or sea-ice points specified in the list of points will be discarded. The model grid will then be a vector @@ -904,14 +903,14 @@ The only configuration that yields a 2D model grid nx = 96, ny = 56, - + # ... / &JULES_LATLON # / - + &JULES_LAND_FRAC # / diff --git a/doc/source/namelists/output.nml.rst b/doc/source/namelists/output.nml.rst index eda92ea4..b8eb0cb8 100644 --- a/doc/source/namelists/output.nml.rst +++ b/doc/source/namelists/output.nml.rst @@ -277,8 +277,6 @@ This namelist should occur :nml:mem:`JULES_OUTPUT::nprofiles` times. Each occurr .. note:: A time-accumulation is initialised at the start of a run and thereafter accumulates until the end of the run. This may mean that accuracy is lost, particularly towards the end of long runs, if small increments are added to an already large sum. Furthermore, before being output the accumulation is multiplied by the number of model timesteps in a sample period. This adjusts the accumulation for any intermittent sampling and is designed so that the time accumulation of a flux (e.g. kg s\ :sup:`-1`) can easily be converted to a total (e.g. kg) by subsequently multiplying by the model timestep length during post processing. - - Example of requesting output ---------------------------- diff --git a/doc/source/namelists/pft_params.nml.rst b/doc/source/namelists/pft_params.nml.rst index 0c18aa84..8f4bb2d0 100644 --- a/doc/source/namelists/pft_params.nml.rst +++ b/doc/source/namelists/pft_params.nml.rst @@ -188,7 +188,7 @@ ease the direct links to these documents are: :type: real(npft) :default: None - Leaf reflection coefficient for VIS (photosyntehtically active radiation). See HCTN30 Table 3. + Leaf reflection coefficient for VIS (photosynthetically active radiation). See HCTN30 Table 3. Always used unless :nml:mem:`JULES_VEGETATION::can_rad_mod` = 1 and :nml:mem:`JULES_RADIATION::l_spec_albedo` = FALSE. @@ -915,19 +915,13 @@ ease the direct links to these documents are: .. seealso:: References: - * Clark et al., 2011, The Joint UK Land Environment Simulator - (JULES), model description – Part 2: Carbon fluxes and - vegetation dynamics, Geosci. Model Dev., 4, 701-722, - https://doi.org/10.5194/gmd-4-701-2011 - * Pinty, B., T. Lavergne, R. E. Dickinson, - J.-L. Widlowski, N. Gobron, and M. M. Verstraete (2006), - Simplifying the interaction of land surfaces with radiation - for relating remote sensing products to climate - models, J. Geophys. Res., 111, D02116, - https://doi.org/10.1029/2005JD005952. - - - + * Clark et al., 2011, The Joint UK Land Environment Simulator (JULES), + model description - Part 2: Carbon fluxes and vegetation dynamics, + Geosci. Model Dev., 4, 701-722, https://doi.org/10.5194/gmd-4-701-2011 + * Pinty, B., T. Lavergne, R. E. Dickinson, J.-L. Widlowski, N. Gobron, + and M. M. Verstraete (2006), Simplifying the interaction of + land surfaces with radiation for relating remote sensing products to + climate models, J. Geophys. Res., 111, D02116, https://doi.org/10.1029/2005JD005952. .. nml:group:: Only used with the Farquhar model of leaf photosynthesis (:nml:mem:`JULES_VEGETATION::photo_model` = 2). A value is required for each PFT, but only those for C\ :sub:`3` plants are used (since only C\ :sub:`3` plants use the Farquhar model). Below, J\ :sub:`max` is the potential rate of electron transport, and V\ :sub:`cmax` is the maximum rate of carboxylation of Rubisco. @@ -984,7 +978,7 @@ ease the direct links to these documents are: Ratio of J\ :sub:`max` to V\ :sub:`cmax` at 25 deg C (mol electrons [mol\ :sup:`-1` CO\ :sub:`2`]). .. note:: - If thermal adaptation or acclimation of photosynthesis is selected (:nml:mem:`JULES_VEGETATION::photo_acclim_model` = 1 or 2) together with :nml:mem:`JULES_VEGETATION::photo_jv_model` =2 (J\ :sub:`max`/V\ :sub:`cmax` calculated assuming constant total nitrogen allocation)), this value is used along with parameters :nml:mem:`JULES_VEGETATION::n_alloc_jmax` and :nml:mem:`JULES_VEGETATION::n_alloc_vcmax` to calculate the final value of J\ :sub:`max`/V\ :sub:`cmax`. + If thermal adaptation or acclimation of photosynthesis is selected (:nml:mem:`JULES_VEGETATION::photo_acclim_model` = 1 or 2) together with :nml:mem:`JULES_VEGETATION::photo_jv_model` =2 (J\ :sub:`max`/V\ :sub:`cmax` calculated assuming constant total nitrogen allocation), this value is used along with parameters :nml:mem:`JULES_VEGETATION::n_alloc_jmax` and :nml:mem:`JULES_VEGETATION::n_alloc_vcmax` to calculate the final value of J\ :sub:`max`/V\ :sub:`cmax`. .. nml:group:: Only used if thermal adaptation or acclimation of photosynthetic capacity is NOT modelled (:nml:mem:`JULES_VEGETATION::photo_acclim_model` = 0). A value is required for each PFT, but only those for C\ :sub:`3` plants are used (since only C\ :sub:`3` plants use the Farquhar model). @@ -995,7 +989,7 @@ ease the direct links to these documents are: :type: real(npft) :default: None - Entropy factor for temperature reponse of J\ :sub:`max` (J mol\ :sup:`-1` K\ :sup:`-1`). + Entropy factor for temperature response of J\ :sub:`max` (J mol\ :sup:`-1` K\ :sup:`-1`). .. nml:member:: ds_vcmax_io @@ -1003,7 +997,7 @@ ease the direct links to these documents are: :type: real(npft) :default: None - Entropy factor for temperature reponse of V\ :sub:`cmax` (J mol\ :sup:`-1` K\ :sup:`-1`). + Entropy factor for temperature response of V\ :sub:`cmax` (J mol\ :sup:`-1` K\ :sup:`-1`). .. nml:group:: Only used if the respiration is modelled using the SUGAR carbohydrate model (:nml:mem:`JULES_VEGETATION::l_sugar` = T). A value is required for each PFT. diff --git a/doc/source/namelists/prescribed_data.nml.rst b/doc/source/namelists/prescribed_data.nml.rst index 3118ab6d..11015f5b 100644 --- a/doc/source/namelists/prescribed_data.nml.rst +++ b/doc/source/namelists/prescribed_data.nml.rst @@ -1,7 +1,6 @@ ``prescribed_data.nml`` ======================= - This file contains a variable number of namelists that are used to prescribe time-varying input data that is not meteorological forcing. The namelist :nml:lst:`JULES_PRESCRIBED` should occur only once at the top of the file. The value of :nml:mem:`JULES_PRESCRIBED::n_datasets` in :nml:lst:`JULES_PRESCRIBED` then determines how many times the namelist :nml:lst:`JULES_PRESCRIBED_DATASET` should occur. @@ -20,7 +19,6 @@ This file contains a variable number of namelists that are used to prescribe tim The number of datasets that will be specified using instances of the :nml:lst:`JULES_PRESCRIBED_DATASET` namelist. - ``JULES_PRESCRIBED_DATASET`` namelist members --------------------------------------------- @@ -33,43 +31,43 @@ This namelist should occur :nml:mem:`JULES_PRESCRIBED::n_datasets` times. Each o .. nml:member:: data_start .. nml:member:: data_end - + :type: character :default: None - + The times of the start of the first timestep of data and the end of the last timestep of data. - + Each run of JULES (configured in :doc:`timesteps.nml`) can use part or all of the specified data. However, there must be data for all times between run start and run end (determined by :nml:mem:`JULES_TIME::main_run_start`, :nml:mem:`JULES_TIME::main_run_end`, :nml:mem:`JULES_SPINUP::spinup_start` and :nml:mem:`JULES_SPINUP::spinup_end`). - + The times must be given in the format:: - + "yyyy-mm-dd hh:mm:ss" - - + + .. nml:member:: data_period - + :type: integer :permitted: -2, -1 or > 0 :default: None - + The period, in seconds, of the data. - + Special cases: - + | **-1:** Monthly data | **-2:** Yearly data - - + + .. nml:member:: is_climatology - + :type: logical :default: F - + Indicates whether the data is to be used as a climatology (use the same data for every year). - + TRUE Interpret the data as a climatology. :nml:mem:`data_start` and :nml:mem:`data_end` must be such that exactly one year of data is specified. - + FALSE Do not interpret the data as a climatology. @@ -77,94 +75,94 @@ This namelist should occur :nml:mem:`JULES_PRESCRIBED::n_datasets` times. Each o .. nml:group:: Members used to specify the files containing the data .. nml:member:: read_list - + :type: logical :default: F - + Switch controlling how data file names are determined for a given time. - + TRUE Use a list of data file names with times of first data. - + FALSE Use a single data file for all times or a template describing the names of the data files. - - + + .. nml:member:: nfiles - + :type: integer :permitted: >= 0 :default: 0 - + Only used if :nml:mem:`read_list` = TRUE. - + The number of data files to read name and time of first data for. - - + + .. nml:member:: file - + :type: character :default: None - + If :nml:mem:`read_list` = TRUE, this is the file to read the list of data file names and times from. Each line should be of the form:: - + '/data/file', 'yyyy-mm-dd hh:mm:ss' - + In this case data file names may contain variable name templating only, with the proviso that either no file names use variable name templating or all file names do. The files must appear in chronological order. - + If :nml:mem:`read_list` = FALSE, this is either the single data file (if no templating is used) or a template for data file names. Both :doc:`time and variable name templating ` may be used. .. nml:group:: Members used to specify the provided variables .. nml:member:: nvars - + :type: integer :permitted: >= 0 :default: 0 - + The number of variables that the dataset will provide. - + See :ref:`supported-prescribed-variables` for the supported variables. - - + + .. nml:member:: var - + :type: character(nvars) :default: None - + List of variable names as recognised by JULES (see :ref:`supported-prescribed-variables`). Names are case sensitive. - + .. note:: For ASCII files, variable names must be in the order they appear in the file. - - + + .. nml:member:: var_name - + :type: character(nvars) :default: '' (empty string) - + For each JULES variable specified in :nml:mem:`var`, this is the name of the variable in the file(s) containing the data. If the empty string (the default) is given for any variable, then the corresponding value from :nml:mem:`var` is used instead. - + .. note:: For ASCII files, this is not used - only the order in the file matters, as described above. - - + + .. nml:member:: tpl_name - + :type: character(nvars) :default: None - + For each JULES variable specified in :nml:mem:`var`, this is the string to substitute into the file name(s) in place of the variable name substitution string. - + If the file name(s) do not use variable name templating, this is not used. - - + + .. nml:member:: interp - + :type: character(nvars) :default: None - + For each JULES variable specified in :nml:mem:`var`, this indicates how the variable is to be interpolated in time (see :doc:`/input/temporal-interpolation`). diff --git a/doc/source/namelists/red_parms.nml.rst b/doc/source/namelists/red_parms.nml.rst index b36c27fe..5ea4c3c8 100644 --- a/doc/source/namelists/red_parms.nml.rst +++ b/doc/source/namelists/red_parms.nml.rst @@ -1,18 +1,26 @@ +``red_parms.nml`` +================= +This file contains a single namelist called :nml:lst:`RED_PARMS` that sets +parameters relevant to the Robust Ecosystem Demography submodel +`(RED version 1.0) `_. +Activate RED in the :nml:mem:`JULES_VEGETATION::l_red`. -This file contains a single namelist called :nml:lst:`JULES_RED` that sets parameters relevant to the Robust Ecosystem Demography submodel (RED version 1.0) `_. -Activate RED in the :nml:mem:`JULES_VEGETATION::l_red. - -``JULES_RED`` namelist members ----------------------------------- +``RED_PARMS`` namelist members +------------------------------ .. nml:namelist:: RED_PARMS -This namelist is used to read PFT parameters that are only needed by the Robust Ecosystem Demography (RED). Values are not used if RED is not selected. +This namelist is used to read PFT parameters that are only needed by the Robust +Ecosystem Demography (RED). Values are not used if RED is not selected. + +.. note:: Where a quantity is said to have units of "/360days", this means that + it is an amount per 360 days. -.. note:: Where a quantity is said to have units of "/360days", this means that it is an amount per 360 days. +.. nml:group:: Only used when :nml:mem:`JULES_VEGETATION::l_red` = TRUE -.. nml:group:: Only used when :nml:mem:`JULES_VEGETATION::l_red = TRUE + This group contains parameters that are only used when RED is enabled in + JULES_VEGETATION. .. nml:member:: alpha_recrt @@ -36,7 +44,8 @@ This namelist is used to read PFT parameters that are only needed by the Robust :default: None The value that describes the competitive hierarchy of PFTs competition in - JULES-RED, the higher the value the more dominant: 3 (trees), 2 (shrubs), 1 (grass). + JULES-RED, the higher the value the more dominant: 3 (trees), 2 (shrubs), + 1 (grass). .. nml:member:: height0 @@ -52,7 +61,8 @@ This namelist is used to read PFT parameters that are only needed by the Robust :type: real(npft) :default: None - The lowest PFT balanced LAI, which corresponds to the mass0 class (m\ :sup:`2`/m\ :sup:`2`). + The lowest PFT balanced LAI, which corresponds to the mass0 class + (m\ :sup:`2`/m\ :sup:`2`). .. nml:member:: mass0 @@ -92,7 +102,8 @@ This namelist is used to read PFT parameters that are only needed by the Robust :type: real(npft) :default: 0.50 - The allometric/power scaling of PFT mass to PFT crown area (West, G. B., et al 2009 `_). + The allometric/power scaling of PFT mass to PFT crown area + (`West, G. B., et al 2009 `_). .. nml:member:: phi_g @@ -100,7 +111,8 @@ This namelist is used to read PFT parameters that are only needed by the Robust :type: real(npft) :default: 0.75 - The allometric/power scaling of PFT mass to PFT mass growth rate (West, G. B., et al., 1997 `_). + The allometric/power scaling of PFT mass to PFT mass growth rate + (`West, G. B., et al., 1997 `_). .. nml:member:: phi_h @@ -108,7 +120,8 @@ This namelist is used to read PFT parameters that are only needed by the Robust :type: real(npft) :default: 0.25 - The allometric/power scaling of PFT mass to PFT height (Niklas, K. J., et al., 2001 `_). + The allometric/power scaling of PFT mass to PFT height + (`Niklas, K. J., et al., 2001 `_). .. nml:member:: phi_l diff --git a/doc/source/namelists/science_fixes.nml.rst b/doc/source/namelists/science_fixes.nml.rst index 1b903ef5..8ebe5c76 100644 --- a/doc/source/namelists/science_fixes.nml.rst +++ b/doc/source/namelists/science_fixes.nml.rst @@ -1,7 +1,6 @@ ``science_fixes.nml`` ===================== - This file contains one namelist called :nml:lst:`JULES_TEMP_FIXES`. This namelist sets 'short-term' temporary logicals used to protect science bug @@ -35,11 +34,11 @@ is retired. See module for when the switch is due for review. :type: logical :default: F - This switch improves the calculation of surface air density in the - surface turbulent fluxes. It includes appropriate use of dry air density - when the atmospheric water vapour is expressed as a mixing ratio - (l_mr_physics = .TRUE.), otherwise use the wet air density when - it is expressed as a specific humidity. + This switch improves the calculation of surface air density in the + surface turbulent fluxes. It includes appropriate use of dry air density + when the atmospheric water vapour is expressed as a mixing ratio + (l_mr_physics = .TRUE.), otherwise use the wet air density when + it is expressed as a specific humidity. .. nml:member:: l_dtcanfix @@ -92,9 +91,9 @@ is retired. See module for when the switch is due for review. :type: logical :default: F - If true, this switch corrects a bug in the surface energy balance + If true, this switch corrects a bug in the surface energy balance when the MORUSES radiative roof coupling is used - (see :nml:mem:`JULES_URBAN::l_moruses_storage`). + (see :nml:mem:`JULES_URBAN::l_moruses_storage`). If false, the thermal conductivity of the soil (hcons) is erroneously set to zero, which causes the roof to be effectively uncoupled when :nml:mem:`JULES_VEGETATION::l_vegcan_soilfx`. @@ -112,7 +111,7 @@ is retired. See module for when the switch is due for review. 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 + Overloaded canopies may be produced by changes in the snow amounts or by reductions in the LAI from which the canopy capacity is calculated. .. nml:member:: l_fix_osa_chloro diff --git a/doc/source/namelists/timesteps.nml.rst b/doc/source/namelists/timesteps.nml.rst index 7670a448..d2ec4e15 100644 --- a/doc/source/namelists/timesteps.nml.rst +++ b/doc/source/namelists/timesteps.nml.rst @@ -25,8 +25,8 @@ This file sets the start and end time of the run. It can also be used to specify FALSE Each year consists of 365 or 366 days. - - + + .. nml:member:: l_leap :type: logical @@ -39,7 +39,7 @@ This file sets the start and end time of the run. It can also be used to specify FALSE Each year consists of 365 days. - + .. nml:member:: l_local_solar_time @@ -53,7 +53,7 @@ This file sets the start and end time of the run. It can also be used to specify FALSE The time convention applying within the model and the driving data is assumed to be UTC. - + .. nml:member:: timestep_len diff --git a/doc/source/namelists/triffid_params.nml.rst b/doc/source/namelists/triffid_params.nml.rst index 59931232..48b18cc4 100644 --- a/doc/source/namelists/triffid_params.nml.rst +++ b/doc/source/namelists/triffid_params.nml.rst @@ -44,7 +44,7 @@ This namelist is used to read PFT parameters that are only needed by the dynamic 0. Natural vegetation. 1. Crop. 2. Pasture. - 3. Bioenergy crops or trees. + 3. Bioenergy crops or trees. .. nml:member:: g_area_io @@ -142,7 +142,7 @@ This namelist is used to read PFT parameters that are only needed by the dynamic 0. No automatic expansion of PFT area when the agricultural area increases. 1. Automatically plant out new crop areas with the selected PFT. -.. nml:group:: Only used when :nml:mem:`JULES_VEGETATION::l_trif_biocrop` = TRUE +.. nml:group:: Only used when :nml:mem:`JULES_VEGETATION::l_trif_biocrop` = TRUE .. nml:member:: harvest_type_io @@ -156,7 +156,7 @@ This namelist is used to read PFT parameters that are only needed by the dynamic .. note:: For "natural" PFTs (:nml:mem:`JULES_TRIFFID::crop_io` = 0), this must be set to 0. For agricultural PFTs, this can be set to 0, 1 or 2. - .. nml:group:: Only used when :nml:mem:`JULES_TRIFFID::harvest_type_io` = 2 + .. nml:group:: Only used when :nml:mem:`JULES_TRIFFID::harvest_type_io` = 2 A placeholder value must be used for all other PFTs. @@ -166,7 +166,7 @@ This namelist is used to read PFT parameters that are only needed by the dynamic :permitted: >= 0 :default: none - Harvest freqency in years. + Harvest freqency in years. .. nml:member:: harvest_ht_io @@ -174,7 +174,7 @@ This namelist is used to read PFT parameters that are only needed by the dynamic :permitted: > 0 :default: none - Height [m] to which the PFT is reduced at each harvest cycle. + Height [m] to which the PFT is reduced at each harvest cycle. - .. note:: :nml:mem:`lai_min_io` must be set such that PFT height at :nml:mem:`lai_min_io` <= :nml:mem:`harvest_ht_io`, otherwise JULES will not start (the required value will be shown in error output). + .. note:: :nml:mem:`lai_min_io` must be set such that PFT height at :nml:mem:`lai_min_io` <= :nml:mem:`harvest_ht_io`, otherwise JULES will not start (the required value will be shown in error output). diff --git a/doc/source/namelists/urban.nml.rst b/doc/source/namelists/urban.nml.rst index e82f7430..b952b2b2 100644 --- a/doc/source/namelists/urban.nml.rst +++ b/doc/source/namelists/urban.nml.rst @@ -1,19 +1,18 @@ ``urban.nml`` ============= - This file contains one namelist called :nml:lst:`JULES_URBAN`. This section predominantly sets the options available for the two-tile urban scheme MORUSES. These namelists are only read if :nml:mem:`JULES_SURFACE::l_urban2t`, which requires both the :nml:mem:`JULES_SURFACE_TYPES::urban_canyon` and :nml:mem:`JULES_SURFACE_TYPES::urban_roof` surface types to be used. MORUSES provides parameters for: snow free canyon albedo (:nml:mem:`JULES_URBAN::l_moruses_albedo`), canyon emissivity (:nml:mem:`JULES_URBAN::l_moruses_emissivity`), roughness length for heat (:nml:mem:`JULES_URBAN::l_moruses_rough`), roughness length for momentum (:nml:mem:`JULES_URBAN::l_moruses_macdonald`) and thermal inertia (:nml:mem:`JULES_URBAN::l_moruses_storage`). Ancillary data, predominantly required for MORUSES, is read in via :nml:lst:`URBAN_PROPERTIES`. -For all other parameters that MORUSES does not provide, and for any MORUSES parametrisations that are turned off, values from :doc:`nveg_params.nml` will be used instead. See the switches below for more information. +For all other parameters that MORUSES does not provide, and for any MORUSES parameterisations that are turned off, values from :doc:`nveg_params.nml` will be used instead. See the switches below for more information. .. seealso:: References: - * Porson, A., et al. (2010), Implementation of a new urban energy budget scheme in the MetUM. Part I: Description and idealized simulations, Quarterly Journal of the Royal Meteorological Society, 136: 1514-1529. doi: 10.1002/qj.668 - * Porson, A., et al. (2010), Implementation of a new urban energy budget scheme into MetUM. Part II: Validation against observations and model Intercomparison, Quarterly Journal of the Royal Meteorological Society, 136: 1530-1542. doi: 10.1002/qj.572 + * Porson, A., et al. (2010), Implementation of a new urban energy budget scheme in the MetUM. Part I: Description and idealized simulations, Quarterly Journal of the Royal Meteorological Society, 136: 1514-1529. doi: 10.1002/qj.668 + * Porson, A., et al. (2010), Implementation of a new urban energy budget scheme into MetUM. Part II: Validation against observations and model Intercomparison, Quarterly Journal of the Royal Meteorological Society, 136: 1530-1542. doi: 10.1002/qj.572 ``JULES_URBAN`` namelist members @@ -104,10 +103,10 @@ For all other parameters that MORUSES does not provide, and for any MORUSES para MORUSES switch for thermal inertia and coupling with the underlying soil for canyon and roof. - MORUSES consists of two surfaces; a canyon (:nml:mem:`JULES_SURFACE_TYPES::urban_canyon`) and a roof (:nml:mem:`JULES_SURFACE_TYPES::urban_roof`). This MORUSES parametrisation calculates the heat capacity of each of these surface types and also modifies how they are coupled with the underlying soil. The heat capacities of the canyon and roof are calculated using the properties of the urban fabric and the geometry of the canyon. The roof has a lower thermal inertia and can respond more rapidly to changes in forcing. The nature of the coupling (radiative, conductive or none) is controlled via :nml:mem:`JULES_NVEGPARM::vf_nvg_io` as descibed below. + MORUSES consists of two surfaces; a canyon (:nml:mem:`JULES_SURFACE_TYPES::urban_canyon`) and a roof (:nml:mem:`JULES_SURFACE_TYPES::urban_roof`). This MORUSES parameterisation calculates the heat capacity of each of these surface types and also modifies how they are coupled with the underlying soil. The heat capacities of the canyon and roof are calculated using the properties of the urban fabric and the geometry of the canyon. The roof has a lower thermal inertia and can respond more rapidly to changes in forcing. The nature of the coupling (radiative, conductive or none) is controlled via :nml:mem:`JULES_NVEGPARM::vf_nvg_io` as descibed below. **The canyon**: - Consists of two walls and a road where the road only is coupled to the underlying soil. The walls are uncoupled and have a zero-flux boundary condition. The coupling of the road is therefore parametrised using a canyon scaling factor. The nature of the canyon (or road surface) coupling is specified as follows: + Consists of two walls and a road where the road only is coupled to the underlying soil. The walls are uncoupled and have a zero-flux boundary condition. The coupling of the road is therefore parameterised using a canyon scaling factor. The nature of the canyon (or road surface) coupling is specified as follows: :nml:mem:`JULES_NVEGPARM::vf_nvg_io` (:nml:mem:`JULES_SURFACE_TYPES::urban_canyon`): = ===================== @@ -175,7 +174,7 @@ For all other parameters that MORUSES does not provide, and for any MORUSES para Switch to use empirical relationships for urban geometry, based on total urban fraction. Dimensions calculated are W/R, H/W and H. - If no MORUSES parametrisations are used, i.e. the basic URBAN-2T, then only W/R is required. + If no MORUSES parameterisations are used, i.e. the basic URBAN-2T, then only W/R is required. If the roof fraction is not supplied i.e. canyon fraction = total urban fraction, then W/R will be used to calculate the canyon and roof fractions. W/R is also used to distribute anthropogenic heat between the roof and the canyon if :nml:mem:`JULES_SURFACE::l_anthrop_heat_src` = TRUE. diff --git a/doc/source/output-variables.rst b/doc/source/output-variables.rst index 65d0ef2b..4349855d 100644 --- a/doc/source/output-variables.rst +++ b/doc/source/output-variables.rst @@ -74,7 +74,7 @@ Variables that are available for output from JULES are listed in this section, s Meteorology ------------------------------------------------------------------- -Unlesss stated otherwise these variables have values at both land and sea points. +Unless stated otherwise these variables have values at both land and sea points. .. tabularcolumns:: |p{2.5cm}|p{10.8cm}|p{2.2cm}| @@ -196,7 +196,7 @@ Radiation Energy and momentum fluxes, and surface temperatures -------------------------------------------------------------------- +---------------------------------------------------- .. tabularcolumns:: |p{3.5cm}|p{9.8cm}|p{2.2cm}| @@ -246,7 +246,7 @@ Energy and momentum fluxes, and surface temperatures Soil moisture and temperature, and soil characteristics -------------------------------------------------------------------- +------------------------------------------------------- .. tabularcolumns:: |p{4.0cm}|p{9.3cm}|p{2.2cm}| @@ -319,7 +319,7 @@ Soil moisture and temperature, and soil characteristics Hydrology -------------------------------------------------------------------- +--------- .. tabularcolumns:: |p{4.6cm}|p{8.7cm}|p{2.2cm}| @@ -413,7 +413,7 @@ Hydrology Rivers -------------------------------------------------------------------- +------ .. tabularcolumns:: |p{4.6cm}|p{8.7cm}|p{2.2cm}| @@ -484,7 +484,7 @@ Rivers Snow -------------------------------------------------------------------- +---- .. tabularcolumns:: |p{4.5cm}|p{8.8cm}|p{2.2cm}| @@ -575,7 +575,7 @@ Snow Vegetation carbon and related fluxes -------------------------------------------------------------------- +------------------------------------ .. tabularcolumns:: |p{3.5cm}|p{9.8cm}|p{2.2cm}| @@ -755,7 +755,7 @@ Vegetation carbon and related fluxes Vegetation nitrogen and related fluxes -------------------------------------------------------------------- +-------------------------------------- .. tabularcolumns:: |p{4.5cm}|p{8.8cm}|p{2.2cm}| @@ -859,7 +859,7 @@ Vegetation nitrogen and related fluxes Soil carbon and related fluxes -------------------------------------------------------------------- +------------------------------ .. tabularcolumns:: |p{4.6cm}|p{8.7cm}|p{2.2cm}| @@ -960,7 +960,7 @@ Soil carbon and related fluxes Soil nitrogen and related fluxes -------------------------------------------------------------------- +-------------------------------- .. tabularcolumns:: |p{4.0cm}|p{9.3cm}|p{2.2cm}| @@ -1057,7 +1057,7 @@ Soil nitrogen and related fluxes Fire -------------------------------------------------------------------- +---- .. tabularcolumns:: |p{4.0cm}|p{9.3cm}|p{2.2cm}| @@ -1158,7 +1158,7 @@ Fire Crops -------------------------------------------------------------------- +----- These variables are only available when :nml:mem:`JULES_SURFACE_TYPES::ncpft` > 0. @@ -1215,7 +1215,7 @@ These variables are only available when :nml:mem:`JULES_SURFACE_TYPES::ncpft` > Trace gas concentrations and fluxes -------------------------------------------------------------------- +----------------------------------- .. tabularcolumns:: |p{3.0cm}|p{10.3cm}|p{2.2cm}| @@ -1248,7 +1248,7 @@ Trace gas concentrations and fluxes Trace gas dry deposition parameters and fluxes -------------------------------------------------------------------- +---------------------------------------------- .. tabularcolumns:: |p{4.5cm}|p{8.8cm}|p{2.2cm}| @@ -1259,7 +1259,7 @@ Trace gas dry deposition parameters and fluxes +---------------------------+--------------------------------------------------------------------------------+------------+ | ``deposition_rb`` | Quasi-laminar resistance (Rb) by chemical tracer (s m\ :sup:`-1`). | tracer | +---------------------------+--------------------------------------------------------------------------------+------------+ -| ``deposition_rc`` | Surface resistance (Rc) by surface type and chemical tracer (s m\ :sup:`-1`). | ntype, | +| ``deposition_rc`` | Surface resistance (Rc) by surface type and chemical tracer (s m\ :sup:`-1`). | ntype, | | | | tracer | +---------------------------+--------------------------------------------------------------------------------+------------+ | ``deposition_rc_stom`` | Stomatal component of surface resistance (Rc) by surface type and | ntype, | @@ -1283,7 +1283,7 @@ Trace gas dry deposition parameters and fluxes Water resources -------------------------------------------------------------------- +--------------- These variables are only available if :nml:mem:`JULES_WATER_RESOURCES::l_water_resources` = TRUE. @@ -1401,7 +1401,7 @@ Urban IMOGEN -------------------------------------------------------------------- +------ .. tabularcolumns:: |p{3.5cm}|p{9.8cm}|p{2.2cm}| @@ -1427,7 +1427,7 @@ IMOGEN Grid and indexing variables -------------------------------------------------------------------- +--------------------------- .. tabularcolumns:: |p{2.5cm}|p{10.8cm}|p{2.2cm}| @@ -1452,5 +1452,4 @@ Grid and indexing variables +--------------------+----------------------------------------------------------------------------------------+------------+ - .. |mu| unicode:: μ .. u diff --git a/doc/source/output.rst b/doc/source/output.rst index 46b2a9e2..89d113fb 100644 --- a/doc/source/output.rst +++ b/doc/source/output.rst @@ -33,13 +33,13 @@ JULES output files contain two time related variables to allow model output to b ``time_bounds`` For each output period, this variable contains two values - the start and end of the output period. The output period is then the half-open interval given by: - + .. code-block:: fortran time_bounds(1) < time <= time_bounds(2) - + This is the interval that means, minima, maxima and accumulations are calculated over. - + During each model timestep, JULES captures values for output at the end of the timestep (i.e. after all the science code). This means that in output files, snapshot data at a particular timestep is: * The state of the model at the end of the model timestep. diff --git a/doc/source/overview/intro.rst b/doc/source/overview/intro.rst index 28445775..df871d12 100644 --- a/doc/source/overview/intro.rst +++ b/doc/source/overview/intro.rst @@ -1,7 +1,8 @@ Overview of JULES ================= -This section provides a brief overview of JULES and an introduction to some of the key switches that determine what the model will simulate in a given run. +This section provides a brief overview of JULES and an introduction to some of +the key switches that determine what the model will simulate in a given run. .. toctree:: overview diff --git a/doc/source/overview/key-switches.rst b/doc/source/overview/key-switches.rst index 1981aba4..9365c48a 100644 --- a/doc/source/overview/key-switches.rst +++ b/doc/source/overview/key-switches.rst @@ -1,18 +1,45 @@ Some key switches ================= -There are many variables that act together to determine how a run of JULES is set up and these are covered in detail in :doc:`/namelists/contents`. Additionally, `configurations `__ illustrate suitable combinations of options. Here we highlight a few key switches that select broad areas of science, particularly for the benefit of new users. - -The phenology model for natural vegetation can be enabled using :nml:mem:`JULES_VEGETATION::l_phenol` which uses the leaf turnover rate to calculate a time-varying Leaf Area Index (LAI). - -To simulate carbon stocks in natural vegetation, the TRIFFID dynamic vegetation model can be enabled via the switch :nml:mem:`JULES_VEGETATION::l_triffid`. When TRIFFID is on, competition between tiles is switched on with :nml:mem:`JULES_VEGETATION::l_veg_compete` and the effect of nitrogen on vegetation growth is enabled via :nml:mem:`JULES_VEGETATION::l_nitrogen`. - -The crop model, which is simulates phenology and carbon stocks in crops, can be switched on by setting the number of crop tiles :nml:mem:`JULES_SURFACE_TYPES::ncpft` to a non-zero value. - -The crop model and TRIFFID cannot currently be used together. To simulate agricultural areas within TRIFFID, a fraction of the gridbox can be reserved for agricultural Plant Functional Types (PFTs) (as defined by :nml:mem:`JULES_TRIFFID::crop_io` > 0). Agricultural PFT competition and a representation of harvest carbon can be switched on with :nml:mem:`JULES_VEGETATION::l_trif_crop`. - -If neither the phenology model nor the crop model are used, LAI for each vegetation tile can be set to a constant (:nml:mem:`JULES_PFTPARM::lai_io`) or a time series or seasonal cycle can be prescribed (:nml:lst:`JULES_PRESCRIBED`). - -To simulate carbon and nitrogen stocks in the soil, the 4-pool model should be selected by setting :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2. This option adds prognostic soil pools and must be used with the TRIFFID vegetation model. If TRIFFID is not used, prescribed soil pools must be invoked via :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 1. Layered soil pools are used if :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = .TRUE.. - -A multi-layer snow model can be selected using :nml:mem:`JULES_SNOW::nsmax`. Parameterisations of surface and subsurface runoff generation are controlled using :nml:mem:`JULES_HYDROLOGY::l_top` and :nml:mem:`JULES_HYDROLOGY::l_pdm`, while the routing of water in rivers uses :nml:mem:`JULES_RIVERS::l_rivers`. +There are many variables that act together to determine how a run of JULES is +set up and these are covered in detail in :doc:`/namelists/contents`. +Additionally, `configurations `__ +illustrate suitable combinations of options. Here we highlight a few key +switches that select broad areas of science, particularly for the benefit of +new users. + +The phenology model for natural vegetation can be enabled using +:nml:mem:`JULES_VEGETATION::l_phenol` which uses the leaf turnover rate to +calculate a time-varying Leaf Area Index (LAI). + +To simulate carbon stocks in natural vegetation, the TRIFFID dynamic vegetation +model can be enabled via the switch :nml:mem:`JULES_VEGETATION::l_triffid`. +When TRIFFID is on, competition between tiles is switched on with +:nml:mem:`JULES_VEGETATION::l_veg_compete` and the effect of nitrogen on +vegetation growth is enabled via :nml:mem:`JULES_VEGETATION::l_nitrogen`. + +The crop model, which is simulates phenology and carbon stocks in crops, can be +switched on by setting the number of crop tiles +:nml:mem:`JULES_SURFACE_TYPES::ncpft` to a non-zero value. + +The crop model and TRIFFID cannot currently be used together. To simulate +agricultural areas within TRIFFID, a fraction of the gridbox can be reserved for +agricultural Plant Functional Types (PFTs) +(as defined by :nml:mem:`JULES_TRIFFID::crop_io` > 0). +Agricultural PFT competition and a representation of harvest carbon can be +switched on with :nml:mem:`JULES_VEGETATION::l_trif_crop`. + +If neither the phenology model nor the crop model are used, LAI for each +vegetation tile can be set to a constant (:nml:mem:`JULES_PFTPARM::lai_io`) +or a time series or seasonal cycle can be prescribed (:nml:lst:`JULES_PRESCRIBED`). + +To simulate carbon and nitrogen stocks in the soil, the 4-pool model should be +selected by setting :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 2. +This option adds prognostic soil pools and must be used with the TRIFFID +vegetation model. If TRIFFID is not used, prescribed soil pools must be +invoked via :nml:mem:`JULES_SOIL_BIOGEOCHEM::soil_bgc_model` = 1. Layered soil pools are used if :nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = .TRUE.. + +A multi-layer snow model can be selected using :nml:mem:`JULES_SNOW::nsmax`. +Parametrisations of surface and subsurface runoff generation are controlled +using :nml:mem:`JULES_HYDROLOGY::l_top` and :nml:mem:`JULES_HYDROLOGY::l_pdm`, +while the routing of water in rivers uses :nml:mem:`JULES_RIVERS::l_rivers`. diff --git a/doc/source/overview/overview.rst b/doc/source/overview/overview.rst index 898f6667..634ecd3f 100644 --- a/doc/source/overview/overview.rst +++ b/doc/source/overview/overview.rst @@ -1,11 +1,38 @@ Overview ======== -This section provides a brief overview of JULES, largely so as to provide background information and introduce terms used in the rest of the manual. Further details can be found at the `JULES website `_ and in the two `JULES description papers `_ (Best et al., 2011, GMD and Clark et al., 2011, GMD). +This section provides a brief overview of JULES, largely so as to provide +background information and introduce terms used in the rest of the manual. +Further details can be found at the `JULES website `__ +and in the two `JULES description papers `__ +(Best et al., 2011, GMD and Clark et al., 2011, GMD). -For both gridded and single point runs, JULES views each gridbox as consisting of a number of surface types. The fractional area of each surface type is either prescribed by the user or modelled by the TRIFFID sub-model. Each surface type is represented by a surface tile, and a separate energy balance is calculated for each surface tile. The gridbox average energy balance is found by weighting the values from each surface tile. In its standard form, JULES recognises nine surface types: broadleaf trees, needleleaf trees, C3 (temperate) grass, C4 (tropical) grass, shrubs, urban, inland water, bare soil and ice. These 9 types are modelled as 9 surface tiles. A land gridbox is either any mixture of the first 8 surface types, or is land ice. Note that, from version 2.0, one is not limited to these 9 standard surface types (unless running TRIFFID). +For both gridded and single point runs, JULES views each gridbox as consisting +of a number of surface types. The fractional area of each surface type is either +prescribed by the user or modelled by the TRIFFID sub-model. Each surface type +is represented by a surface tile, and a separate energy balance is calculated +for each surface tile. The gridbox average energy balance is found by weighting +the values from each surface tile. In its standard form, JULES recognises nine +surface types: broadleaf trees, needleleaf trees, C3 (temperate) grass, +C4 (tropical) grass, shrubs, urban, inland water, bare soil and ice. +These 9 types are modelled as 9 surface tiles. A land gridbox is either any +mixture of the first 8 surface types, or is land ice. Note that, from +version 2.0, one is not limited to these 9 standard surface types (unless running TRIFFID). -Soil processes are modelled in several layers. Each surface tile can be associated with its own soil tile, or all surface tiles can interact with a shared soil column. Each gridbox requires meteorological driving variables (such as air temperature) and variables that describe the soil properties at that location. It is also possible to prescribe certain characteristics of the vegetation, such as Leaf Area Index, to vary between gridboxes. +Soil processes are modelled in several layers. Each surface tile can be +associated with its own soil tile, or all surface tiles can interact with a +shared soil column. Each gridbox requires meteorological driving variables +(such as air temperature) and variables that describe the soil properties at +that location. It is also possible to prescribe certain characteristics of the +vegetation, such as Leaf Area Index, to vary between gridboxes. -JULES can be run for any number of gridboxes from one upwards. The number of gridboxes is limited by the availability of computing power and suitable input data. When run on a grid, JULES models the average state of the land surface within the area of the gridbox and most quantities are taken to be homogeneous within the gridbox (with options to include subgrid-scale variability of a few, such as rainfall). In that case, the input data are also area averages. JULES can also be run "at a point", with inputs that are taken to represent conditions at that point - this configuration might be used when field measurements of meteorological conditions are available. +JULES can be run for any number of gridboxes from one upwards. The number of +gridboxes is limited by the availability of computing power and suitable +input data. When run on a grid, JULES models the average state of the land +surface within the area of the gridbox and most quantities are taken to be +homogeneous within the gridbox (with options to include subgrid-scale +variability of a few, such as rainfall). In that case, the input data are also +area averages. JULES can also be run "at a point", with inputs that are taken +to represent conditions at that point - this configuration might be used when +field measurements of meteorological conditions are available. diff --git a/doc/source/release_notes/JULES3-0.rst b/doc/source/release_notes/JULES3-0.rst index a32b968c..1c3f7143 100644 --- a/doc/source/release_notes/JULES3-0.rst +++ b/doc/source/release_notes/JULES3-0.rst @@ -8,7 +8,7 @@ The major change in version 3.0 is the introduction of the IMOGEN impacts tool. * New process understanding can be tested for its global implications. * New process understanding can also be checked for stability before full inclusion in a GCM. * By adding climate change anomalies to datasets such as the CRU dataset, then GCM biases can be removed. - + It must be recognised that the system is "off-line", and so if major changes to the land surface occur there might be local and regional feedbacks that can only be predicted using a fully coupled GCM. Hence IMOGEN doesn't replace GCMs, but it does give a very powerful first-look as to potential land surface changes in an anthropogenically forced varying climate. This was accomplished with help from Mark Lomas at the University of Sheffield and Chris Huntingford at CEH. There are also several small bug fixes: diff --git a/doc/source/release_notes/JULES3-1.rst b/doc/source/release_notes/JULES3-1.rst index 52288505..dd2ee0de 100644 --- a/doc/source/release_notes/JULES3-1.rst +++ b/doc/source/release_notes/JULES3-1.rst @@ -26,11 +26,13 @@ The user interface also sees significant changes. The monolithic .jin run contro Other changes ------------- +.. |eacute| replace:: é + There are several not-insignificant changes to the science code: * Structures are now used for dimensioning variables - this allows for more flexibility of grids than the old system of row_length/rows and halos. * Move to a new implicit solver - ``sf_impl2`` is now used rather than ``sf_impl`` for consistency with the UM. However, the way the implicit coupling is set up means it operates in a similar way to the old scheme. -* A change in the way fresh snow is handled in the multi-layer snow scheme - the density of fresh snow is now prescribed by a new variable (``rho_snow_fresh``). Suggested by Cécile Ménard and implemented by Doug Clark. +* A change in the way fresh snow is handled in the multi-layer snow scheme - the density of fresh snow is now prescribed by a new variable (``rho_snow_fresh``). Suggested by C|eacute|cile M|eacute|nard and implemented by Doug Clark. * Bug fix from Doug Clark for the multi-layer snow scheme that fixes problems with the model oscillating between 0 and 1 snow layers every timestep, preventing snow melt. * Changes to the sea-ice surface exchange when operating as part of the UM. This will not affect the majority of users. * Slight changes to the coupling between the explicit and implicit schemes. The vast majority of users will not need to worry about this. diff --git a/doc/source/release_notes/JULES3-3.rst b/doc/source/release_notes/JULES3-3.rst index 210e4434..6bc60c6b 100644 --- a/doc/source/release_notes/JULES3-3.rst +++ b/doc/source/release_notes/JULES3-3.rst @@ -35,19 +35,19 @@ Disambiguation of sea ice roughness lengths for heat and momentum Improvements to the numerics in the soil hydrology Previously, the soil hydrology scheme coped poorly with significant gradients in soil moisture because of the sensitive dependence of the hydraulic conductivity and soil water suction on the soil moisture. See the new switch ``l_dpsids_dsdz``. - + Implicit numerics for land ice Previously, the updating of land ice temperatures was always explicit, limiting the thickness of soil levels that can be used with standard time steps. There is now an option for implicit numerics for land ice - see the new switch ``l_land_ice_imp``. - + Scaling of land surface albedo to agree with a given input An option has been added to prescribe the grid-box mean snow-free albedo to a given input (e.g. observations, climatology). See the new switch ``l_albedo_obs``. For SW albedos, the albedos of the individual tiles are scaled linearly so that the grid-box mean albedo matches the observations, within limits for each tile. When VIS and NIR albedos are required then the input parameters are scaled and corrected in a similar manner. The change was included in the Global Land configuration at vn5.0: https://code.metoffice.gov.uk/trac/GL/ticket/8. - + BVOC emissions now on a switch Previously, BVOC emissions diagnostics were calculated all the time, regardless of whether they were output. A new switch - ``l_bvoc_emis`` - has been added to enable the calculation of these diagnostics only when required. - + Improvements to logging A new namelist file - ``logging.nml`` - has been added to give more control over log output from JULES. Previously all output was directed to ``stdout``. - + Specify namelist directory as an argument It is now possible to specify the directory containing the namelist files as a command line argument to JULES. If no argument is given, JULES looks for the namelist files in the current working directory. Previously, JULES had to be executed in the directory containing the namelists - this change should make it easier to run JULES in batch mode. diff --git a/doc/source/release_notes/JULES3-4.rst b/doc/source/release_notes/JULES3-4.rst index a1651987..d55ac777 100644 --- a/doc/source/release_notes/JULES3-4.rst +++ b/doc/source/release_notes/JULES3-4.rst @@ -37,7 +37,7 @@ Other changes Tidying of boundary layer code Some small changes have been made to tidy up some of the boundary layer code (i.e. routines in ``src/science/surface``) - this is mostly removing unused variables and tidying up subroutine argument lists. - + OpenMP related changes Some `OpenMP `_ directives have been added to certain loops. OpenMP is a form of shared-memory parallelism in which the user inserts directives (specially formatted code comments) providing information that allows the compiler to parallelise sections of code (in particular loops) without worrying about corrupting data. It is used in the UM, but is currently not enabled when compiling JULES standalone. diff --git a/doc/source/release_notes/JULES4-0.rst b/doc/source/release_notes/JULES4-0.rst index 274ef731..f28fd3f0 100644 --- a/doc/source/release_notes/JULES4-0.rst +++ b/doc/source/release_notes/JULES4-0.rst @@ -25,7 +25,7 @@ JULES vn4.0 also sees a major revamp of the science-related namelists. The monol This has been with the aim of providing a GUI for editing the JULES namelists using `Rose `_, which is now available - see :doc:`/building-and-running/rose`. -It also has the advantage that the new namelists are cut-and-paste-able between the UM and JULES, which should make it easier to ensure that the same science is being used in online and offline runs. +It also has the advantage that the new namelists are cut-and-paste-able between the UM and JULES, which should make it easier to ensure that the same science is being used in online and offline runs. Removal of GNU make build files @@ -40,11 +40,11 @@ Directory structure Dependencies * The JULES GNU Makefiles required that dependencies be manually maintained, both in terms of the order of sub-makes and actual file dependencies within the sub-makes. * FCM make automatically detects all dependencies and does things in the correct order. - + Parallel builds * JULES builds with GNU make could not be parallelised, because of the use of directory level sub-makes. * FCM make considers each individual file, so builds can be parallelised. - + Integration with Rose * FCM make has good integration with Rose, allowing the Rose GUI for JULES to configure and run builds as well as the namelists. diff --git a/doc/source/release_notes/JULES4-1.rst b/doc/source/release_notes/JULES4-1.rst index c025cae0..3cd876cd 100644 --- a/doc/source/release_notes/JULES4-1.rst +++ b/doc/source/release_notes/JULES4-1.rst @@ -3,14 +3,14 @@ JULES version 4.1 Release Notes Irrigation demand ------------------ +----------------- When enabled, irrigation demand adds water to the soil moisture up to the critical point, meaning that vegetation does not experience water stress. At the moment the amount of water added is not limited, although it will be limited in a future version. -There are two schemes that can be used to determine when to irrigate: - +There are two schemes that can be used to determine when to irrigate: + 1. This method calculates optimum planting dates for non-rice crops using averages from driving data and so requires at least one year of driving data. It was written by Nic Gedney and is based on the crop calendar from Doell & Siebert (2002). -2. Uses development index (dvi) across all tiles from JULES-crop (written by Rutger Dankers). Maximum dvi must exceed -1 (indicates sowing) for irrigation to occur. +2. Uses development index (dvi) across all tiles from JULES-crop (written by Rutger Dankers). Maximum dvi must exceed -1 (indicates sowing) for irrigation to occur. See the documentation for :nml:mem:`JULES_IRRIG::l_irrig_dmd` for more details. diff --git a/doc/source/release_notes/JULES4-8.rst b/doc/source/release_notes/JULES4-8.rst index 96bfabd7..f6abfa57 100644 --- a/doc/source/release_notes/JULES4-8.rst +++ b/doc/source/release_notes/JULES4-8.rst @@ -62,7 +62,7 @@ Bugs fixed * Bug fix for albpft_jls.F90 (#458) * Bug fix to allow compilation without netCDF (#464) * Bug fixes for metadata and upgrade macro (#404, #459, #490) - + Documentation updates --------------------- Coding standards, and documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES4-9.rst b/doc/source/release_notes/JULES4-9.rst index 190b5145..e8e92ccd 100644 --- a/doc/source/release_notes/JULES4-9.rst +++ b/doc/source/release_notes/JULES4-9.rst @@ -58,7 +58,7 @@ Bugs fixed * Corrected a bug in the sea ice albedo scheme, which affects the calculation of bare ice albedo when multilayer thermodynamics are used in coupled UM-JULES-NEMO-CICE. (#547) * Bug fix to variable intent in surf_couple_implicit. (#542) * Bug fix for UM runs relating to clash between STASH items (#557) - + Documentation updates --------------------- Coding standards, and documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES5-0.rst b/doc/source/release_notes/JULES5-0.rst index b0af5d40..dd44b78b 100644 --- a/doc/source/release_notes/JULES5-0.rst +++ b/doc/source/release_notes/JULES5-0.rst @@ -44,7 +44,7 @@ Bugs fixed * Enables ability to perform bit comparable NRUN in the UM. (#612) * Fix JULES rose stem so that it works on the MO XCS-C system (aka MONSooN). (#615) * Fixed broken hyperlinks in the user guide. (#636) - + Documentation updates --------------------- Documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES5-1.rst b/doc/source/release_notes/JULES5-1.rst index ff665a4d..3baf4a32 100644 --- a/doc/source/release_notes/JULES5-1.rst +++ b/doc/source/release_notes/JULES5-1.rst @@ -56,7 +56,7 @@ Bugs fixed * Bug in tiling that could affect lake quantities (in UM runs using FLake). (#641) * Fix of a minor OpenMP race condition. (#674) * Moved an ALLOCATE statement to fix a memory bug in the UM affecting ESM runs. (#639) - + Documentation updates --------------------- Documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES5-2.rst b/doc/source/release_notes/JULES5-2.rst index 6a1a5c71..35c9a587 100644 --- a/doc/source/release_notes/JULES5-2.rst +++ b/doc/source/release_notes/JULES5-2.rst @@ -30,7 +30,7 @@ General/Technical changes * JULES parameters included in the Random Parameter (RP) scheme (for UM runs). (#675) * Rationalised some of the code for the reading and writing of dumps. (#763) * Alignment of JULES and UM urban control and initialisation code. (#319) - * Reduced model overhead when running DrHook profiling. (#782) + * Reduced model overhead when running DrHook profiling. (#782) * Fixed oddities found while investigating the use of CamFort. (#769) * JULES source code fully compliant with the Fortran 2003 standard. (#711) * Corrections to code comments and other minor changes. (#725, 690) @@ -64,7 +64,7 @@ Bugs fixed * Fix of host specification in `runtime.rc` for site cehwl1. (#731) * Updated the configuration for University of Exeter (`uoe-linux-gfortran.cfg`). (#735) * Fix so rose stem IMOGEN tests work at NCI. (#792) - + Documentation updates --------------------- * Removed the science configurations section from the documentation. (#736). diff --git a/doc/source/release_notes/JULES5-3.rst b/doc/source/release_notes/JULES5-3.rst index e5af4753..b6227b32 100644 --- a/doc/source/release_notes/JULES5-3.rst +++ b/doc/source/release_notes/JULES5-3.rst @@ -49,7 +49,7 @@ Changes to testing * Implemented code to align continuation ampersands in column 79 as part of `umdp3_fixer.py`. (#823) * The Met Office rose stem suite now runs all Linux tasks on SPICE, and the metadata checker task is now included in the JASMIN rose stem suite. (#819) * Correction for rose stem on MONSooN. (#852) - + Documentation updates --------------------- diff --git a/doc/source/release_notes/JULES5-4.rst b/doc/source/release_notes/JULES5-4.rst index c00f1efd..c5650081 100644 --- a/doc/source/release_notes/JULES5-4.rst +++ b/doc/source/release_notes/JULES5-4.rst @@ -51,7 +51,7 @@ Changes to testing * Rose-stem fcm-make tasks will ignore lock files that would otherwise prevent retriggering. (#860) * Expanded coverage of the rose-stem metadata validation test to include more apps. (#886) * Upgraded ``suite_report.py``. (#889) - + Documentation updates --------------------- diff --git a/doc/source/release_notes/JULES5-6.rst b/doc/source/release_notes/JULES5-6.rst index ff0e8807..a3b7da36 100644 --- a/doc/source/release_notes/JULES5-6.rst +++ b/doc/source/release_notes/JULES5-6.rst @@ -28,7 +28,7 @@ General/Technical changes * Altered OMP directives to remove data race conditions. (#952) * Removed the requirement to have some environment variables that are used in build configs defined/initiliased at the app/suite level. (#939) - + Changes to testing ------------------ * Updated rose stem testing to include JULES-ES-1.0 configuration. (#915) diff --git a/doc/source/release_notes/JULES5-7.rst b/doc/source/release_notes/JULES5-7.rst index 4fdd432e..d3a53cce 100644 --- a/doc/source/release_notes/JULES5-7.rst +++ b/doc/source/release_notes/JULES5-7.rst @@ -35,7 +35,7 @@ General/Technical changes * Fixed the make_jules_release script to push latest documentation onto the master on GitHub. (#957) * The example namelists (difficult to maintain) and benchmarking suite (obselete) have been removed. (#928, 969) - + Bugs fixed ---------- diff --git a/doc/source/release_notes/JULES5-8.rst b/doc/source/release_notes/JULES5-8.rst index 0714ab6b..ff9d9cc6 100644 --- a/doc/source/release_notes/JULES5-8.rst +++ b/doc/source/release_notes/JULES5-8.rst @@ -19,7 +19,7 @@ General/Technical changes * Access the gather_field and scatter_field subroutines via modules. (#1051) * The url fields in HEAD metadata now have the "latest" tag, allowing both the UM and JULES to have the same url field. (#1017) - + Bugs fixed ---------- diff --git a/doc/source/release_notes/JULES5-9.rst b/doc/source/release_notes/JULES5-9.rst index b02beb50..475e0f6a 100644 --- a/doc/source/release_notes/JULES5-9.rst +++ b/doc/source/release_notes/JULES5-9.rst @@ -30,7 +30,7 @@ General/Technical changes * All transparent, non-functional metadata consolidated with the UM, including `sort-key`, `description`, `url` and `help`, which has been removed where duplicated by the JULES user guide or merged in. (#1055) * Keep standalone and UM JULES meta data consistent. (#1083) - + Bugs fixed ---------- diff --git a/doc/source/release_notes/JULES6-0.rst b/doc/source/release_notes/JULES6-0.rst index b9470ba3..1b4e7a63 100644 --- a/doc/source/release_notes/JULES6-0.rst +++ b/doc/source/release_notes/JULES6-0.rst @@ -30,7 +30,7 @@ General/Technical changes * Fixed bad characters in metadata. (#1103) * Further work to keep JULES and UM metadata consistent. (#1118) - + Bugs fixed ---------- diff --git a/doc/source/release_notes/JULES6-1.rst b/doc/source/release_notes/JULES6-1.rst index a78728ae..416e94cb 100644 --- a/doc/source/release_notes/JULES6-1.rst +++ b/doc/source/release_notes/JULES6-1.rst @@ -24,7 +24,7 @@ General/Technical changes * Improved performance in RA3 configurations. (#1113) * Added further platform files for JASMIN. (#1145) - + Bugs fixed ---------- @@ -34,7 +34,7 @@ Bugs fixed * Prevent memory issues when using the INFERNO fire scheme in UM configurations. (#1149) * Bug fix to add Rose metadata and upgrade macro for :nml:lst:`JULES_VEGETATION_PROPS` namelist. (#1141) - + Changes to testing ------------------ diff --git a/doc/source/release_notes/JULES6-2.rst b/doc/source/release_notes/JULES6-2.rst index 47b54e48..40e69303 100644 --- a/doc/source/release_notes/JULES6-2.rst +++ b/doc/source/release_notes/JULES6-2.rst @@ -30,7 +30,7 @@ General/Technical changes * Updated Python scripts to be Python 3 compatible. (#1091) * Preparing the JULES vn6.2 release. (#1204) - + Bugs fixed ---------- @@ -40,7 +40,7 @@ Bugs fixed * Prevent error in internal write of ctile_orog_fix (potentially many characters long) into a 3 character buffer. (#1205) * Fix arguments to subroutine next_time. (#1209) - + Documentation updates --------------------- diff --git a/doc/source/release_notes/JULES6-3.rst b/doc/source/release_notes/JULES6-3.rst index b0f2b648..c305993c 100644 --- a/doc/source/release_notes/JULES6-3.rst +++ b/doc/source/release_notes/JULES6-3.rst @@ -39,7 +39,7 @@ General/Technical changes * Added a further restriction on the type of processor used for rose stem testing on JASMIN. (#1222) * Updated list of module leaders. (#1240) - + Bugs fixed ---------- @@ -50,7 +50,7 @@ Bugs fixed * Ensured that soileccose types are set up correctly. (#1229) * Ensured Python3 is in path on both MONSooN and JASMIN systems. (#1216, 1231) - + Documentation updates --------------------- diff --git a/doc/source/release_notes/JULES7-0.rst b/doc/source/release_notes/JULES7-0.rst index be5695e1..f431fe67 100644 --- a/doc/source/release_notes/JULES7-0.rst +++ b/doc/source/release_notes/JULES7-0.rst @@ -30,7 +30,7 @@ General/Technical changes * Passing CABLE vars (TYPEs) from top level through to and into surf_couple layer. (#1226) * Updated the module load of the make_jules_release script. (#1263) - + Bugs fixed ---------- diff --git a/doc/source/release_notes/JULES7-1.rst b/doc/source/release_notes/JULES7-1.rst index a0357852..f43edb60 100644 --- a/doc/source/release_notes/JULES7-1.rst +++ b/doc/source/release_notes/JULES7-1.rst @@ -11,43 +11,43 @@ Ticket numbers are indicated below, e.g. #931. Science changes --------------- - * Interactive gas-phase deposition routines from UKCA have been added to JULES, together with a variant version that removes the restriction on the surface tile configuration. See :nml:mem:`JULES_DEPOSITION::dry_dep_model`. (#931) + * Interactive gas-phase deposition routines from UKCA have been added to JULES, together with a variant version that removes the restriction on the surface tile configuration. See :nml:mem:`JULES_DEPOSITION::dry_dep_model`. (#931) General/Technical changes ------------------------- - * Added a switch to allow interpretation of times in the model and the driving data as local solar time - see :nml:mem:`JULES_TIME::l_local_solar_time`. (#1327) - * Added a switch :nml:mem:`IMOGEN_RUN_LIST::l_drive_with_global_temps` so that JULES can be driven with global temperatures and climate patterns. (#1322) - * Made Medlyn stomatal conductance, Farquhar C\ :sub:`3` photosynthesis, and thermal acclimation available in the UM. (#1246) - * Further work towards allowing layered soil carbon (:nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = TRUE ) in the UM. (#1237) - * A varying grey tile emissivity has been passed in to JULES - currently only available if selected in LFRic. (#1247) - * OMP improvements in various routines. (#1310) - * Enabled a call to CABLE albedo (part of ongoing work to provide access to CABLE). (#1314) - * MORUSES and anthropogenic heat related metadata migrated to jules-shared to facilitate their implementation in LFRic. The simple two-tile urban scheme now no longer requires W/R as an input unless the total urban fraction only is specified in the ancillary data. (#1255) - * Included the fab_jules app which builds JULES using Fab software. (#1331, 1364) - * Updated compiler in JASMIN gfortran platform file. (#1347) - * Upgraded rose stem testing on Met Office EXZ to use latest availiable CPE, and fixes for EXZ. (#1362, 1358) - - + * Added a switch to allow interpretation of times in the model and the driving data as local solar time - see :nml:mem:`JULES_TIME::l_local_solar_time`. (#1327) + * Added a switch :nml:mem:`IMOGEN_RUN_LIST::l_drive_with_global_temps` so that JULES can be driven with global temperatures and climate patterns. (#1322) + * Made Medlyn stomatal conductance, Farquhar C\ :sub:`3` photosynthesis, and thermal acclimation available in the UM. (#1246) + * Further work towards allowing layered soil carbon (:nml:mem:`JULES_SOIL_BIOGEOCHEM::l_layeredc` = TRUE ) in the UM. (#1237) + * A varying grey tile emissivity has been passed in to JULES - currently only available if selected in LFRic. (#1247) + * OMP improvements in various routines. (#1310) + * Enabled a call to CABLE albedo (part of ongoing work to provide access to CABLE). (#1314) + * MORUSES and anthropogenic heat related metadata migrated to jules-shared to facilitate their implementation in LFRic. The simple two-tile urban scheme now no longer requires W/R as an input unless the total urban fraction only is specified in the ancillary data. (#1255) + * Included the fab_jules app which builds JULES using Fab software. (#1331, 1364) + * Updated compiler in JASMIN gfortran platform file. (#1347) + * Upgraded rose stem testing on Met Office EXZ to use latest available CPE, and fixes for EXZ. (#1362, 1358) + + Bugs fixed ---------- - * Corrected a bug in the `surf_ht_flux` diagnostic when using the Flake lake model. (#1340) - * Fixing problems in the WARNING output messages. (#1303) - * Fixed a metadata/rose config error introduced by a bug in Rose. (#1363) + * Corrected a bug in the `surf_ht_flux` diagnostic when using the Flake lake model. (#1340) + * Fixing problems in the WARNING output messages. (#1303) + * Fixed a metadata/rose config error introduced by a bug in Rose. (#1363) Changes to testing ------------------ - * Updated NCI rose stem tests. (#1266) + * Updated NCI rose stem tests. (#1266) Documentation updates --------------------- - * Updates associated with many of the above changes and to module leaders file, and release notes. (#1275, 1343) + * Updates associated with many of the above changes and to module leaders file, and release notes. (#1275, 1343) Documentation can be viewed on the github page ``_. diff --git a/doc/source/release_notes/JULES7-2.rst b/doc/source/release_notes/JULES7-2.rst index cd770894..7e14e6e0 100644 --- a/doc/source/release_notes/JULES7-2.rst +++ b/doc/source/release_notes/JULES7-2.rst @@ -20,7 +20,7 @@ General/Technical changes * Increase compile-time checking with Cray's CCE. (#1061) * Updated configuration for NIWA. (#1387) - + Bugs fixed ---------- diff --git a/doc/source/release_notes/JULES7-3.rst b/doc/source/release_notes/JULES7-3.rst index b9c059b8..d197ab99 100644 --- a/doc/source/release_notes/JULES7-3.rst +++ b/doc/source/release_notes/JULES7-3.rst @@ -19,7 +19,7 @@ General/Technical changes * Change kind type names to avoid clash with Fortran intrinsics. (#1408) * Removed some include files by moving code to module files. (#1411, 1412. 1418) - + Bugs fixed ---------- diff --git a/doc/source/release_notes/JULES7-4.rst b/doc/source/release_notes/JULES7-4.rst index 7f46dd60..575ced5c 100644 --- a/doc/source/release_notes/JULES7-4.rst +++ b/doc/source/release_notes/JULES7-4.rst @@ -23,7 +23,7 @@ General/Technical changes * Added prognostic variables for the RED vegetation model to model dump files. (#1230) * Adding water tracers to the surface scheme - the first stage of adding water tracers/isotopes to JULES. (#1390) - + Bugs fixed ---------- diff --git a/doc/source/release_notes/JULES7-5.rst b/doc/source/release_notes/JULES7-5.rst index dbcf37d6..98895daf 100644 --- a/doc/source/release_notes/JULES7-5.rst +++ b/doc/source/release_notes/JULES7-5.rst @@ -26,7 +26,7 @@ General/Technical changes * ModuleLeaders file renamed for consistency with other projects. (#1452) - + Bugs fixed ---------- diff --git a/doc/source/release_notes/JULES7-6.rst b/doc/source/release_notes/JULES7-6.rst index 5d004e24..2333861e 100644 --- a/doc/source/release_notes/JULES7-6.rst +++ b/doc/source/release_notes/JULES7-6.rst @@ -10,7 +10,7 @@ Ticket numbers are indicated below, e.g. #1512. General/Technical changes ------------------------- - * Changes to how river ancillary files are processed. (#1512) + * 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) @@ -19,7 +19,7 @@ General/Technical changes * 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 ---------- diff --git a/doc/source/release_notes/JULES7-7.rst b/doc/source/release_notes/JULES7-7.rst index 2ed02a59..a74f1096 100644 --- a/doc/source/release_notes/JULES7-7.rst +++ b/doc/source/release_notes/JULES7-7.rst @@ -12,7 +12,7 @@ General/Technical changes * Initialisation related to the CaMa-Flood model of river routing and inundation. Note that this model is still in development and cannot yet be used. (#1000) * Developments to allow the blending height to be increased and passed between timesteps - for use with the UM atmospheric model. (#1500) - + Bugs fixed ---------- diff --git a/doc/source/release_notes/JULES7-8.rst b/doc/source/release_notes/JULES7-8.rst index 92d480c5..2c23b9b1 100644 --- a/doc/source/release_notes/JULES7-8.rst +++ b/doc/source/release_notes/JULES7-8.rst @@ -16,7 +16,7 @@ General/Technical changes * Allowing JULES to be used on the Met Office's Azspice system. Change to the default EX machine for rose stem and allowing use of EXCD. (#1576, 1580, 1585) * Updates for the upgraded JASMIN system. (#1586) - + Bugs fixed ---------- diff --git a/doc/source/release_notes/JULES7-9.rst b/doc/source/release_notes/JULES7-9.rst index e761122f..28aba146 100644 --- a/doc/source/release_notes/JULES7-9.rst +++ b/doc/source/release_notes/JULES7-9.rst @@ -26,7 +26,7 @@ General/Technical changes * Allow JULES to build using Fab on azspice at the Met Office. (#1596) * Provide a set up for rivers-only jobs on the Met Office EX machines. (1598) - + Bugs fixed ---------- diff --git a/doc/source/release_notes/JULES8-0.rst b/doc/source/release_notes/JULES8-0.rst index 625ebae7..22252d19 100644 --- a/doc/source/release_notes/JULES8-0.rst +++ b/doc/source/release_notes/JULES8-0.rst @@ -22,7 +22,7 @@ General/Technical changes * The river number ancillary (used for coupling to the ocean model) has been updated with one consistent with the river routing ancillary. They now pass the rivers ancillary checking routine, hence `l_ignore_ancil_rivers_check` has been removed. (#1460) * Code for CABLE removed for licensing purposes. The CABLE code will only reside within its own repository and will be included at compilation time in future releases. (#1633) - + Bugs fixed ---------- @@ -45,3 +45,8 @@ Documentation updates Documentation can be viewed on the github page ``_. +After migrating to GitHub, the JULES code repository is now available at +`https://github.com/MetOffice/jules `_. +The user guide documentation is also included and can be accessed at +`https://metoffice.github.io/jules/ `_. + From 965271a2bf813a1f2def21439fe1533b29068f79 Mon Sep 17 00:00:00 2001 From: Yaswant Pradhan <2984440+yaswant@users.noreply.github.com> Date: Wed, 26 Nov 2025 14:21:22 +0000 Subject: [PATCH 3/3] Update pyproject.toml --- doc/pyproject.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/pyproject.toml b/doc/pyproject.toml index 54fee1ce..a9703ac0 100644 --- a/doc/pyproject.toml +++ b/doc/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "jules" -version = "0.1.0" -description = "Add your description here" +version = "8.0.0" +description = "Joint UK Land Environment Simulator User Guide" readme = "README.md" requires-python = ">=3.13" dependencies = [
  • vn{self.vnumber}